# Integrating OfficeCLI with Cursor: A Complete MCP Setup Guide

> Integrate OfficeCLI with Cursor using the MCP server for seamless AI control of Word Excel and PowerPoint docs via JSONRPC No fragile shell parsing needed

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-10

---

**OfficeCLI integrates with Cursor through its built-in Model Context Protocol (MCP) server, allowing AI agents to manipulate Word, Excel, and PowerPoint documents via deterministic JSON-RPC calls without fragile shell parsing.**

Integrating **OfficeCLI** with **Cursor** transforms how developers automate Office document workflows. The tool exposes a native **Model Context Protocol (MCP)** layer that registers the CLI as a first-class tool within Cursor's agent framework. This architecture eliminates the need for screen scraping or complex DOM manipulation, instead offering type-safe, headless OOXML operations directly from AI prompts.

## Understanding the OfficeCLI Architecture for Cursor Integration

OfficeCLI operates through three distinct layers that enable seamless Cursor integration. Understanding these layers clarifies how the AI agent communicates with Office documents without requiring Microsoft Office installation.

### The Three Operating Layers

The codebase organizes functionality into separate concerns:

1. **Command-line layer** – Traditional invocations using `officecli <command>` for direct shell execution.
2. **Resident/pipe layer** – A thin SDK available in Python and Node that communicates with the binary over a named pipe for low-latency, multi-step workflows.
3. **MCP server layer** – A built-in **Model Context Protocol** JSON-RPC server that exposes all CLI functionality to AI agents including Cursor, Claude Code, and VS Code Copilot.

The MCP layer resides in the core binary and activates when running specific registration commands.

### How the MCP Server Bridges Cursor and Office Documents

When active, the MCP server listens on `localhost:26315` by default and exposes a JSON-RPC endpoint. According to the [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) documentation, this server handles command serialization, error formatting, and deterministic output parsing. The server translates Cursor's natural language requests into structured `officecli` commands, executes them in a headless environment, and returns standardized JSON responses that Cursor can consume programmatically.

## Setting Up OfficeCLI MCP Integration with Cursor

The registration process requires a single command that configures the tool descriptor file and launches the background server.

### Installation and Registration

First, install OfficeCLI using the one-liner provided in the repository's [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md):

```bash

# Install OfficeCLI (cross-platform binary)

curl -fsSL https://iofficeai.github.io/install.sh | bash

```

Execute the Cursor-specific registration command:

```bash
officecli mcp cursor

```

This command performs two critical operations: it writes a **skill file** ([`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md)) to `~/.cursor/skills/officecli.md` (or the appropriate platform-specific config directory), and it launches the MCP server on the default port. The skill file instructs Cursor how to start the server, which commands are available (`create`, `add`, `set`, `view`, `dump`, etc.), and that every command supports deterministic JSON output via the `--json` flag.

### Verification

After registration, verify the server is responding by checking the local endpoint:

```bash
curl -X POST http://127.0.0.1:26315/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"run","params":{"command":["officecli","--version"]}}'

```

## How Cursor Communicates with OfficeCLI

Cursor interacts with OfficeCLI through structured JSON-RPC payloads rather than raw shell execution, providing type safety and structured error handling.

### JSON-RPC Protocol Details

The MCP server accepts POST requests at `http://127.0.0.1:26315/rpc` with standard JSON-RPC 2.0 formatting. Each request includes a method name (`run`), a command array, and a unique identifier. Responses follow the error-handling specification documented in [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md), returning objects like `{ "success": true, "path": "/slide[3]" }` or detailed failure messages.

### Deterministic Output with JSON Flags

When Cursor invokes commands, it automatically appends the `--json` flag to ensure machine-readable output. This eliminates parsing ambiguity from human-formatted text, allowing Cursor to extract file paths, slide indices, and cell references directly from response objects.

## Practical Usage Examples

These implementations demonstrate how Cursor leverages OfficeCLI for document automation.

### Basic Document Modification via Cursor

When a user prompts Cursor to *"Add a slide titled Q4 Results to deck.pptx"*, Cursor constructs and sends the following JSON-RPC payload:

```json
POST http://127.0.0.1:26315/rpc
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "run",
  "params": {
    "command": [
      "officecli",
      "add",
      "deck.pptx",
      "/",
      "--type",
      "slide",
      "--prop",
      "title=Q4 Results",
      "--json"
    ]
  }
}

```

The server returns a structured confirmation:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "path": "/slide[3]"
  }
}

```

### Batch Operations for Complex Workflows

For multi-step operations that Cursor should execute atomically, use the batch command to reduce API round-trips:

```bash
officecli batch deck.pptx --commands '[{"op":"add","path":"/","type":"slide","props":{"title":"Q4 Results"}},{"op":"add","path":"/slide[1]","type":"shape","props":{"text":"Revenue ↑ 25%"}}]' --json

```

This approach minimizes latency when Cursor generates multiple mutations from a single user request.

### Live Preview Integration

The `watch` command implementation in [`src/officecli/Resources/watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js) powers a live preview server. Cursor can open `http://localhost:26315` to display document changes instantly after each mutation:

```bash
officecli watch deck.pptx

```

This SSE (Server-Sent Events) endpoint updates the preview without reloading, giving Cursor a visual feedback loop for document edits.

### SDK Integration (Python Example)

For Python-based Cursor extensions or scripts, the SDK automatically manages the MCP server lifecycle:

```python
from officecli import Doc

with Doc("deck.pptx") as d:
    d.add("/", type="slide", title="Q4 Results")
    print(d.get("/slide[3]"))

```

The [`npm/officecli.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js) wrapper provides equivalent functionality for Node.js environments, pulling the native binary and forwarding calls through the pipe layer.

## Key Files and Implementation Details

Understanding these source files clarifies the integration mechanics:

| File | Role |
|------|------|
| [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) | Primary documentation containing the Cursor MCP command reference and usage examples |
| [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) | Tool descriptor that Cursor reads to auto-install and configure OfficeCLI |
| [`src/officecli/Resources/watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js) | Implements the live-preview SSE server infrastructure |
| [`npm/officecli.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js) | NPM wrapper for cross-platform binary distribution |
| [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) | Thin Node SDK that communicates over the named pipe layer |

These components work together to provide the `officecli mcp cursor` functionality, the skill file installation process, and the headless document manipulation capabilities that Cursor relies upon.

## Summary

- **OfficeCLI** exposes a **built-in MCP server** that transforms the CLI into a Cursor-native tool via JSON-RPC on `localhost:26315`.
- Running **`officecli mcp cursor`** registers the tool by writing a skill file to the Cursor configuration directory and launching the server.
- Cursor communicates through **structured JSON-RPC payloads** rather than shell parsing, using the `--json` flag for deterministic output.
- The **`watch`** command and SSE implementation in [`watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js) provide live document previews for visual feedback.
- **Batch operations** allow Cursor to execute complex multi-step workflows in a single request, optimizing for AI agent efficiency.

## Frequently Asked Questions

### What is the default port for the OfficeCLI MCP server?

The OfficeCLI MCP server listens on **port 26315** by default. This HTTP endpoint accepts JSON-RPC 2.0 POST requests at the `/rpc` path, allowing Cursor to submit commands as structured arrays rather than raw shell strings.

### Does integrating OfficeCLI with Cursor require Microsoft Office installation?

No. OfficeCLI operates entirely **headless** without requiring Microsoft Office, LibreOffice, or any GUI environment. The binary performs direct OOXML manipulation, making it suitable for Docker containers, CI pipelines, and remote development environments where traditional Office suites cannot run.

### Where does Cursor store the OfficeCLI skill configuration?

The `officecli mcp cursor` command writes a **skill file** ([`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md)) to the Cursor-specific configuration directory, typically located at `~/.cursor/skills/officecli.md` on Unix systems or equivalent paths on Windows and macOS. This markdown file describes available commands, parameters, and the MCP endpoint location.

### Can I use OfficeCLI with Cursor for Excel and Word documents, or only PowerPoint?

OfficeCLI supports **Word (.docx), Excel (.xlsx), and PowerPoint (.pptx)** formats through the same MCP interface. The `add`, `set`, `view`, and `dump` commands work across all three formats, with Cursor automatically handling format-specific parameters like cell references for Excel or slide indices for PowerPoint.