How to Integrate OfficeCLI with Claude Code Using the MCP Server

Run officecli mcp claude to start a persistent stdio-based JSON-RPC server that registers OfficeCLI as a Claude Code skill, enabling direct document manipulation without spawning new processes.

This guide shows you how to integrate OfficeCLI with Claude Code through the built-in MCP (Model-Context Protocol) server. The iOfficeAI/OfficeCLI repository ships native support for Claude Code's agent-skill system, letting AI assistants create, edit, and view Word, Excel, and PowerPoint documents through structured JSON-RPC calls.

How the OfficeCLI MCP Server Works

The integration operates through three architectural layers that bridge the CLI binary with Claude Code:

Layer	Purpose	Implementation Location
Early-Dispatch	Intercepts mcp, skills, and install arguments before standard parsing	CommandBuilder.IntegrationStubs.cs
MCP Server	Listens on stdin/stdout, decodes JSON-RPC requests, routes to command handlers	Binary implementation (see mcp command)
Skill Registration	Writes officecli.md to Claude Code's skill directory (~/.claude/skills/)	SKILL.md file

Early-Dispatch Handling

In CommandBuilder.IntegrationStubs.cs, stub commands are defined to surface mcp functionality in help output:

// From CommandBuilder.IntegrationStubs.cs
["mcp"] = "Start the MCP stdio server ..."

When officecli mcp claude is invoked, Program.cs rewrites arguments to launch the MCP server and trigger skill registration before the generic System.CommandLine parser processes the command.

JSON-RPC Command Format

Once running, the server exposes every OfficeCLI verb (create, add, set, view, etc.) through a unified command method:

// Request format
{"command":"add","file":"report.pptx","parent":"/","type":"slide","props":{"title":"Q4 Results"}}

// Response format
{"success":true,"path":"/slide[1]"}

Because the server runs inside the same process as the binary, there's zero overhead from shell spawning. Claude Code receives predictable, schema-validated JSON responses for every operation.

Register OfficeCLI with Claude Code

One-Line Installation

officecli mcp claude

This command performs three actions:

1. Starts the stdio-based JSON-RPC server
2. Writes ~/.claude/skills/officecli.md containing the SKILL.md definition
3. Prints a status line and enters listen mode for incoming RPC calls

The server remains running until terminated, waiting for Claude Code to pipe JSON requests via stdin.

Verify Registration Status

officecli mcp list

Remove the Registration

officecli mcp claude --unregister

Calling OfficeCLI from Claude Code

Python Integration Example

Claude Code can invoke OfficeCLI through the MCP stdio pipe using any language. Here's a Python implementation:

import json
import subprocess

def officecli_mcp(payload: dict) -> dict:
    """Send JSON-RPC request to OfficeCLI MCP server."""
    proc = subprocess.Popen(
        ["officecli", "mcp", "claude"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        text=True,
    )
    stdout, _ = proc.communicate(json.dumps(payload) + "\n")
    return json.loads(stdout)

# Create a new PowerPoint deck

result = officecli_mcp({"command": "create", "file": "deck.pptx"})

# → {"success": true, "path": "deck.pptx"}

# Add a titled slide

result = officecli_mcp({
    "command": "add",
    "file": "deck.pptx",
    "parent": "/",
    "type": "slide",
    "props": {"title": "Q4 Report"}
})

# → {"success": true, "path": "/slide[1]"}

# Add a shape with text

result = officecli_mcp({
    "command": "add",
    "file": "deck.pptx",
    "parent": "/slide[1]",
    "type": "shape",
    "props": {
        "text": "Revenue ↑ 25%",
        "x": "2cm",
        "y": "5cm"
    }
})

# → {"success": true, "path": "/slide[1]/shape[2]"}

Direct CLI Workflow

For scenarios where Claude Code manages the process lifecycle:

# Start MCP server in background

officecli mcp claude &

# Execute commands through normal CLI with --json flag

officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Growth Metrics" --prop x=3cm --prop y=4cm --json

# Generate HTML preview for visual feedback

officecli view deck.pptx html -o /tmp/deck.html

The --json flag ensures output matches the MCP server's response schema, maintaining consistency between direct CLI usage and RPC calls.

Key Integration Files

File	Purpose	Location
SKILL.md	Claude Code skill definition with install instructions and command help	Repository root
CommandBuilder.IntegrationStubs.cs	Stub commands for mcp, skills, install	src/officecli/
npm/officecli.js	Node.js wrapper exposing MCP capabilities to JavaScript agents	npm/
README.md	Public MCP command documentation and JSON output schemas	Repository root

The SKILL.md file is particularly important—it contains the structured metadata Claude Code uses to understand OfficeCLI's capabilities, parameter types, and return formats.

Advanced: Custom MCP Clients

Any tool speaking JSON-RPC over stdio can communicate with OfficeCLI. The protocol requires:

• Request: Single-line JSON object with command key
• Response: Single-line JSON object with success boolean and result payload
• Delimiter: Newline-terminated messages

This design lets you integrate OfficeCLI with other AI systems beyond Claude Code, provided they can manage the stdio pipe.

Summary

• Run officecli mcp claude to start the MCP server and register with Claude Code in one step
• The server exposes all OfficeCLI commands as JSON-RPC methods through a single command interface
• No process spawning overhead: Commands execute inside the persistent server process
• Predictable schemas: All responses follow documented JSON structures from the README
• Skill auto-loading: Claude Code discovers capabilities through the generated ~/.claude/skills/officecli.md file

Frequently Asked Questions

What MCP protocol version does OfficeCLI use?

OfficeCLI implements Model-Context Protocol over stdio/stdout using JSON-RPC 2.0 format. The server listens for newline-delimited JSON requests and emits single-line JSON responses, as documented in the README's "MCP Server" section.

Can I use OfficeCLI MCP with other AI assistants besides Claude Code?

Yes. Any system capable of spawning a subprocess and communicating via stdin/stdout can drive OfficeCLI. The npm/officecli.js wrapper demonstrates JavaScript integration. Custom clients must follow the {"command": "..."} request format and parse the {"success": ..., ...} response structure.

Why does the mcp claude command stay running instead of exiting?

The MCP server operates as a persistent daemon. By keeping the process alive, it eliminates startup overhead for subsequent commands and maintains internal state. Claude Code manages this lifecycle automatically; for manual testing, run it in background with & or use subprocess pipes as shown in the Python example.

Where does Claude Code load the OfficeCLI skill from?

The registration writes to ~/.claude/skills/officecli.md based on the repository's SKILL.md file. This path follows Claude Code's agent-skill convention. If the skill doesn't appear, verify the file exists and restart Claude Code to trigger skill discovery.

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