che-word-mcp

A Swift-native MCP (Model Context Protocol) server for Microsoft Word document (.docx) manipulation. This is the first Swift OOXML library that directly manipulates Office Open XML without any third-party Word dependencies.

中文說明

Features

• Pure Swift Implementation: No Node.js, Python, or external runtime required
• Direct OOXML Manipulation: Works directly with XML, no Microsoft Word installation needed
• Single Binary: Just one executable file
• 146 MCP Tools: Comprehensive document manipulation capabilities
• Dual-Mode Access: Direct Mode (read-only, one step) and Session Mode (full lifecycle)
• Complete OOXML Support: Full support for tables, styles, images, headers/footers, comments, footnotes, and more
• Cross-platform: Works on macOS (and potentially other platforms supporting Swift)

Version History

Installation

Option 1: Download from Release (Recommended)

Download the latest release from GitHub Releases:

• CheWordMCP - Universal Binary (arm64 + x86_64)
• che-word-mcp.mcpb - MCPB package

# Download and install
curl -L https://github.com/PsychQuant/che-word-mcp/releases/latest/download/CheWordMCP -o ~/bin/CheWordMCP
chmod +x ~/bin/CheWordMCP

Option 2: Build from Source

Prerequisites

• macOS 13.0+ (Ventura or later)
• Swift 5.9+

git clone https://github.com/PsychQuant/che-word-mcp.git
cd che-word-mcp
swift build -c release

The binary will be located at .build/release/CheWordMCP

Add to Claude Code

claude mcp add che-word-mcp /path/to/che-word-mcp/.build/release/CheWordMCP

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-word-mcp": {
      "command": "/path/to/che-word-mcp/.build/release/CheWordMCP"
    }
  }
}

Two Modes of Operation

Direct Mode (source_path) — Read-only, no state

Pass a file path directly. No need to call open_document first. Best for quick inspection.

# Just pass source_path — one step
list_images: { "source_path": "/path/to/file.docx" }
search_text: { "source_path": "/path/to/file.docx", "query": "keyword" }
get_document_info: { "source_path": "/path/to/file.docx" }

18 tools support Direct Mode:

Session Mode (doc_id) — Full read/write lifecycle

Call open_document first, then use doc_id for all subsequent operations. Required for editing.

open_document: { "path": "/path/to/file.docx", "doc_id": "mydoc" }
insert_paragraph: { "doc_id": "mydoc", "text": "Hello World" }
save_document: { "doc_id": "mydoc", "path": "/path/to/output.docx" }
close_document: { "doc_id": "mydoc" }

Dual-mode tools accept both source_path and doc_id. If you already have a document open, use doc_id to avoid re-reading from disk.

Usage with AI Agents

Just ask the agent

Use che-word-mcp to read all images from ~/Documents/report.docx

The agent will automatically use Direct Mode (no need to open/close).

AGENTS.md / CLAUDE.md

## Word Document Manipulation

Use `che-word-mcp` for reading and writing Microsoft Word (.docx) files.

**Read-only** (Direct Mode — one step):
- `get_document_text` / `get_paragraphs` — read content
- `list_images` / `search_text` — inspect elements
- `export_markdown` — convert to Markdown

**Edit** (Session Mode — open→edit→save):
1. `open_document` → get doc_id
2. `insert_paragraph` / `replace_text` / `format_text` — modify
3. `save_document` → write to disk
4. `close_document` → release memory

Claude Code Skill

mkdir -p .claude/skills/che-word-mcp
curl -o .claude/skills/che-word-mcp/SKILL.md \
  https://raw.githubusercontent.com/PsychQuant/che-word-mcp/main/skills/che-word-mcp/SKILL.md

Available Tools (83 Total)

Document Management (6 tools)

Content Operations (6 tools)

Formatting (3 tools)

Tables (6 tools)

Style Management (4 tools)

Lists (3 tools)

Page Setup (5 tools)

Headers & Footers (5 tools)

Images (6 tools)

Export (2 tools)

Hyperlinks & Bookmarks (6 tools)

Comments & Revisions (10 tools)

Footnotes & Endnotes (4 tools)

Field Codes (7 tools)

Repeating Sections (1 tool)

Advanced Features (9 tools)

Usage Examples

Create a Document with Headings and Text

Create a new Word document called "report" with:
- Title: "Quarterly Report"
- Heading: "Introduction"
- A paragraph explaining the report purpose
Save it to ~/Documents/report.docx

Create a Document with Table and Images

Create a document with:
- A title "Product Catalog"
- Insert an image from ~/images/logo.png
- A 4x3 table with product information
- Apply borders to the table
Save it to ~/Documents/catalog.docx

Create a Professional Report

Create a document with:
- Custom page margins (1 inch all around)
- A header with company name
- A footer with page numbers
- Table of contents
- Multiple sections with headings
- Footnotes for references
Save it as ~/Documents/annual_report.docx

Technical Details

OOXML Structure

The server generates valid Office Open XML documents with complete structure:

document.docx (ZIP)
├── [Content_Types].xml
├── _rels/
│   └── .rels
├── word/
│   ├── document.xml      # Main content
│   ├── styles.xml        # Style definitions
│   ├── settings.xml      # Document settings
│   ├── fontTable.xml     # Font definitions
│   ├── numbering.xml     # List definitions
│   ├── comments.xml      # Comments
│   ├── footnotes.xml     # Footnotes
│   ├── endnotes.xml      # Endnotes
│   ├── header1.xml       # Header content
│   ├── footer1.xml       # Footer content
│   ├── media/            # Embedded images
│   │   └── image*.{png,jpeg}
│   └── _rels/
│       └── document.xml.rels
└── docProps/
    ├── core.xml          # Metadata
    └── app.xml           # Application info

Dependencies

• MCP Swift SDK (v0.10.2+) - Model Context Protocol implementation
• ooxml-swift (v0.2.0+) - OOXML parsing
• word-to-md-swift (v0.1.0+) - Word to Markdown conversion

Comparison with Other Solutions

Performance

Benchmarks on Apple Silicon (M4 Max, 128GB RAM):

Read Performance

Write Performance

Why So Fast?

• Native Swift binary - No interpreter startup overhead
• Direct OOXML manipulation - No Microsoft Word process
• Efficient ZIP handling - ZIPFoundation for compression
• In-memory operations - Only writes to disk on save

Compared to python-docx (~200ms startup) or docx npm (~150ms startup), che-word-mcp is 10-20x faster.

License

MIT License

Author

Che Cheng (@kiki830621)

Related Projects

• che-apple-mail-mcp - Apple Mail MCP server
• che-ical-mcp - macOS Calendar MCP server