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

> Learn to integrate OfficeCLI with AI coding agents like Claude Code or Cursor in three simple steps. Enhance your workflow and enable powerful document operations with this guide.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md):

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

```

This performs two operations defined in [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
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

```bash
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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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):

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

```json
{
  "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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) and implemented across the codebase.

### Auto-Detect and Install

The installation routine in [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) and [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js), published as `@officecli/sdk`):

```javascript
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md).

**Python SDK** (`officecli-sdk`):

```python
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) | Skill definition with install commands and auto-detect logic | root |
| [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js) | Node wrapper for the `@officecli/sdk` package | `npm/` |
| [`npm/package.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/package.json) | NPM package metadata for SDK distribution | `npm/` |
| [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) | MCP/JSON-RPC protocol specification | `plugins/` |

## Summary

- **Install via curl**: The [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) also recognizes VS Code and other MCP-compatible environments. The protocol in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.