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
• 105 MCP Tools: Comprehensive document manipulation capabilities
• 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/kiki830621/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/kiki830621/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"
    }
  }
}

Usage with AI Agents

Just ask the agent

The simplest approach - just tell your agent to use it:

Use che-word-mcp to create a new Word document with title "Report" and save it to ~/Documents/report.docx

The agent will automatically use the MCP tools if che-word-mcp is configured.

AGENTS.md / CLAUDE.md

For more consistent results, add to your project or global instructions file:

## Word Document Manipulation

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

Core workflow:
1. `open_document` - Open an existing .docx file
2. `get_text` / `get_paragraphs` - Read document content
3. `insert_paragraph` / `format_text` - Modify content
4. `save_document` - Save changes

Creating new documents:
1. `create_document` - Create new document
2. Add content with `insert_paragraph`, `insert_table`, etc.
3. `save_document` - Save to .docx file

Export options:
- `export_text` - Export as plain text
- `export_markdown` - Export as Markdown

Claude Code Skill

For Claude Code, a skill provides richer context:

# Download the skill
mkdir -p .claude/skills/che-word-mcp
curl -o .claude/skills/che-word-mcp/SKILL.md \
  https://raw.githubusercontent.com/kiki830621/che-word-mcp/main/skills/che-word-mcp/SKILL.md

Or copy from the repository:

cp -r /path/to/che-word-mcp/skills/che-word-mcp .claude/skills/

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.0+) - Model Context Protocol implementation
• ZIPFoundation (v0.9.0+) - ZIP compression/decompression

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