Integrating OfficeCLI with Cursor: A Complete MCP Setup Guide

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 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:

# Install OfficeCLI (cross-platform binary)

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

Execute the Cursor-specific registration command:

officecli mcp cursor

This command performs two critical operations: it writes a skill file (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:

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, 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:

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:

{
  "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:

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 powers a live preview server. Cursor can open http://localhost:26315 to display document changes instantly after each mutation:

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:

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 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	Primary documentation containing the Cursor MCP command reference and usage examples
SKILL.md	Tool descriptor that Cursor reads to auto-install and configure OfficeCLI
src/officecli/Resources/watch-sse-core.js	Implements the live-preview SSE server infrastructure
npm/officecli.js	NPM wrapper for cross-platform binary distribution
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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}