How to Integrate OfficeCLI with AI Coding Agents like Claude Code or Cursor

OfficeCLI integrates with Claude Code, Cursor, and other AI agents through a three-step flow: install the self-contained binary, register the MCP JSON-RPC server via officecli mcp <agent>, and load the skill file that teaches the agent how to invoke document operations.

OfficeCLI is architected from the ground up for AI agent interoperability. According to the iOfficeAI/OfficeCLI source code, the tool exposes every document operation through the Model Context Protocol (MCP), enabling agents to read, write, and manipulate Office files without requiring Microsoft Office installation or COM interop. This guide covers the complete integration workflow using actual repository paths and command structures.

Step 1: Install the Binary and Auto-Register the Skill

The foundation of OfficeCLI integration is a single self-contained executable. The install command downloads this binary and automatically registers the skill file for detected AI agents.

Run the one-line bootstrap from SKILL.md:

curl -fsSL https://officecli.ai/SKILL.md | bash

This performs two operations defined in SKILL.md:

• Downloads the platform-appropriate binary to your system PATH
• Detects installed AI tooling (Claude Code, Cursor, VS Code, etc.) and writes the skill file to the appropriate configuration directory

For Claude Code, this creates ~/.claude/skills/officecli.md. For Cursor, the equivalent path is used. No manual configuration is required.

Verify installation:

officecli --version

Step 2: Register the MCP Server for Your Agent

OfficeCLI exposes document operations as JSON-RPC tools through the mcp sub-command. This bridges the CLI into the agent's native tool-call channel.

Claude Code Registration

officecli mcp claude

This starts the MCP server on default port 26315 and registers the tool schema with Claude Code's execution environment.

Cursor Registration

officecli mcp cursor

The same server runs with a different agent identifier, ensuring Cursor receives the appropriate tool metadata.

The MCP server is specified in plugins/plugin-protocol.md and implemented to publish a tool schema derived from the CLI's help system. Every command returns deterministic JSON when invoked through this channel.

Step 3: Invoke Operations via JSON-RPC

Once registered, AI agents call OfficeCLI through structured JSON-RPC requests rather than shell command parsing.

Example request structure (as sent by an agent):

curl -X POST http://localhost:26315 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"officecli","params":["add","deck.pptx","/","--type","slide","--prop","title=Q4 Results"],"id":1}'

Response format is guaranteed deterministic through the --json flag. All commands accept this flag, producing fixed-schema output like:

{
  "tag": "shape",
  "path": "/slides/0/shapes/1",
  "attributes": {
    "type": "title",
    "text": "Q4 Results"
  }
}

This contract enables LLMs to reason about operation success, detect errors, and drive iterative correction loops without human intervention.

Architectural Features for Agent Integration

OfficeCLI provides several agent-specific capabilities documented in README.md and implemented across the codebase.

Auto-Detect and Install

The installation routine in SKILL.md and README.md scans known configuration directories for AI tooling. This eliminates manual skill registration. The binary placement and skill file writing occur atomically.

Deterministic JSON API

Every command supports --json output with fixed schemas. This is implemented in the core CLI (src/officecli/officecli.csproj) and documented in the command reference section of README.md. Agents rely on this predictability for autonomous operation chains.

Resident Mode with Live Preview

The officecli open and watch commands keep documents in memory, pushing updates to a local HTTP server. Agents query this endpoint for rendered HTML or PNG screenshots, providing visual feedback in headless CI environments.

# Start resident mode with preview server

officecli open document.pptx --watch --preview-port 8080

# Agent queries for visual state

curl http://localhost:8080/render.png

SDK Wrappers for Programmatic Access

Thin SDKs embed the binary and expose identical JSON-RPC methods. These automatically trigger MCP registration on first use.

Node.js SDK (npm/officecli.js, published as @officecli/sdk):

const oc = require("@officecli/sdk");

(async () => {
  const doc = await oc.create("deck.pptx");
  await doc.send({ 
    command: "add", 
    parent: "/", 
    type: "slide", 
    props: { title: "Q4 Results" } 
  });
  console.log(await doc.send({ command: "view", mode: "outline" }));
  await doc.close();
})();

The SDK auto-installs the binary if missing, matching the behavior of SKILL.md.

Python SDK (officecli-sdk):

import officecli

with officecli.create("report.docx") as doc:
    doc.send({
        "command": "add", 
        "parent": "/body", 
        "type": "paragraph",
        "props": {"text": "Executive Summary", "style": "Heading1"}
    })
    print(doc.send({"command": "view", "mode": "outline"}))

Key Integration Files

File	Purpose	Location
SKILL.md	Skill definition with install commands and auto-detect logic	root
README.md	User guide covering mcp commands and JSON-RPC contract	root
src/officecli/officecli.csproj	.NET project building the self-contained binary	src/officecli/
npm/officecli.js	Node wrapper for the @officecli/sdk package	npm/
npm/package.json	NPM package metadata for SDK distribution	npm/
plugins/plugin-protocol.md	MCP/JSON-RPC protocol specification	plugins/

Summary

• Install via curl: The SKILL.md bootstrap downloads the binary and auto-registers skills for detected agents
• Register with officecli mcp: Starts JSON-RPC on port 26315 for Claude Code, Cursor, or other agents
• Rely on deterministic JSON: All commands accept --json with fixed schemas for reliable agent parsing
• Use resident mode: open/watch commands provide live preview endpoints for visual feedback loops
• Leverage SDKs: Node and Python wrappers embed the binary and auto-register on first use

Frequently Asked Questions

What AI agents are officially supported by OfficeCLI?

OfficeCLI officially supports Claude Code and Cursor through dedicated mcp sub-commands. The auto-detect logic in SKILL.md also recognizes VS Code and other MCP-compatible environments. The protocol in plugins/plugin-protocol.md is generic enough that any MCP-compliant agent can integrate.

Does OfficeCLI require Microsoft Office to be installed?

No. OfficeCLI is a self-contained .NET binary with no dependency on Microsoft Office, COM interop, or native platform libraries. This is enforced by the build configuration in src/officecli/officecli.csproj, which produces a single executable with all dependencies bundled.

How does an agent know which OfficeCLI commands are available?

The MCP server publishes a complete tool schema derived from the CLI's internal help system. This schema includes every command, its parameters, and expected return types. Agents receive this schema during registration and use it to construct valid JSON-RPC calls without hardcoded command knowledge.

Can I use OfficeCLI programmatically without the MCP server?

Yes. The Node.js SDK (@officecli/sdk) and Python SDK (officecli-sdk) provide direct programmatic access. Both embed the binary and expose identical functionality to the CLI. The SDKs auto-install the binary and optionally register the MCP server on first initialization.

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