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
| Version | Date | Changes |
|---|
| v1.16.0 | 2026-03-10 | Dual-Mode: 15 read-only tools now support source_path (Direct Mode); MCP server instructions added |
| v1.15.2 | 2026-03-07 | Improve list_all_formatted_text tool description for better LLM parameter handling |
| v1.15.1 | 2026-03-01 | Fix heading heuristic style fallback (resolve fontSize from style inheritance chain) |
| v1.15.0 | 2026-03-01 | Practical Mode: EMFβPNG auto-conversion + heading heuristic for style-less documents |
| v1.14.0 | 2026-03-01 | Embed word-to-md-swift library: no external macdoc binary needed, restore doc_id support |
| v1.13.0 | 2026-03-01 | Upgrade ooxml-swift to v0.5.0: parallel multi-core parsing (~0.64s for large docs) |
| v1.12.1 | 2026-03-01 | Upgrade ooxml-swift to v0.4.0: large document performance fix (>30s β ~2.3s) |
| v1.12.0 | 2026-02-28 | export_markdown uses source_path only, removes doc_id, adds lock file check |
| v1.11.1 | 2026-02-28 | Fix export_markdown stdout mode (pipe fsync issue) |
| v1.11.0 | 2026-02-28 | export_markdown delegates to macdoc CLI; removed word-to-md-swift dependency |
| v1.9.0 | 2026-02-28 | export_markdown upgraded to use word-to-md-swift for high-quality output (145 total) |
| v1.8.0 | 2026-02-03 | Remove hard diff limit, add max_results & heading_styles params to compare_documents |
| v1.7.0 | 2026-02-03 | Add compare_documents tool for server-side document diff (105 total) |
| v1.2.1 | 2026-01-16 | Fix MCP SDK compatibility (actorβclass, add capabilities) |
| v1.2.0 | 2026-01-16 | Add 12 new tools (95 total): search, hyperlinks, bookmarks, footnotes, endnotes, revisions, properties |
| v1.1.0 | 2026-01-16 | Fix MCPB manifest.json format for Claude Desktop |
| v1.0.0 | 2026-01-16 | Initial release with 83 tools, refactored to use ooxml-swift |
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"
}
}
}
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:
| Category | Tools |
|---|
| Read content | get_text, get_document_text, get_paragraphs, get_document_info, search_text |
| List elements | list_images, list_styles, get_tables, list_comments, list_hyperlinks, list_bookmarks, list_footnotes, list_endnotes, get_revisions |
| Properties | get_document_properties, get_section_properties, get_word_count_by_section |
| Export | export_markdown |
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/kiki830621/che-word-mcp/main/skills/che-word-mcp/SKILL.md
Available Tools (83 Total)
Document Management (6 tools)
| Tool | Description |
|---|
create_document | Create a new Word document |
open_document | Open an existing .docx file |
save_document | Save document to .docx file |
close_document | Close an open document |
list_open_documents | List all open documents |
get_document_info | Get document statistics |
Content Operations (6 tools)
| Tool | Description |
|---|
get_text | Get plain text content |
get_paragraphs | Get all paragraphs with formatting |
insert_paragraph | Insert a new paragraph |
update_paragraph | Update paragraph content |
delete_paragraph | Delete a paragraph |
replace_text | Search and replace text |
Formatting (3 tools)
| Tool | Description |
|---|
format_text | Apply text formatting (bold, italic, color, font) |
set_paragraph_format | Set paragraph formatting (alignment, spacing) |
apply_style | Apply built-in or custom styles |
Tables (6 tools)
| Tool | Description |
|---|
insert_table | Insert a table with optional data |
get_tables | Get all tables information |
update_cell | Update cell content |
delete_table | Delete a table |
merge_cells | Merge cells horizontally or vertically |
set_table_style | Set table borders and shading |
Style Management (4 tools)
| Tool | Description |
|---|
list_styles | List all available styles |
create_style | Create custom style |
update_style | Update style definition |
delete_style | Delete custom style |
Lists (3 tools)
| Tool | Description |
|---|
insert_bullet_list | Insert bullet list |
insert_numbered_list | Insert numbered list |
set_list_level | Set list indentation level |
Page Setup (5 tools)
| Tool | Description |
|---|
set_page_size | Set page size (A4, Letter, etc.) |
set_page_margins | Set page margins |
set_page_orientation | Set portrait or landscape |
insert_page_break | Insert page break |
insert_section_break | Insert section break |
Headers & Footers (5 tools)
| Tool | Description |
|---|
add_header | Add header content |
update_header | Update header content |
add_footer | Add footer content |
update_footer | Update footer content |
insert_page_number | Insert page number field |
Images (6 tools)
| Tool | Description |
|---|
insert_image | Insert inline image (PNG, JPEG) |
insert_floating_image | Insert floating image with text wrap |
update_image | Update image properties |
delete_image | Delete image |
list_images | List all images |
set_image_style | Set image border and effects |
Export (2 tools)
| Tool | Description |
|---|
export_text | Export as plain text |
export_markdown | Export as Markdown |
Hyperlinks & Bookmarks (6 tools)
| Tool | Description |
|---|
insert_hyperlink | Insert external hyperlink |
insert_internal_link | Insert link to bookmark |
update_hyperlink | Update hyperlink |
delete_hyperlink | Delete hyperlink |
insert_bookmark | Insert bookmark |
delete_bookmark | Delete bookmark |
Comments & Revisions (10 tools)
| Tool | Description |
|---|
insert_comment | Insert comment |
update_comment | Update comment text |
delete_comment | Delete comment |
list_comments | List all comments |
reply_to_comment | Reply to existing comment |
resolve_comment | Mark comment as resolved |
enable_track_changes | Enable track changes |
disable_track_changes | Disable track changes |
accept_revision | Accept revision |
reject_revision | Reject revision |
Footnotes & Endnotes (4 tools)
| Tool | Description |
|---|
insert_footnote | Insert footnote |
delete_footnote | Delete footnote |
insert_endnote | Insert endnote |
delete_endnote | Delete endnote |
Field Codes (7 tools)
| Tool | Description |
|---|
insert_if_field | Insert IF conditional field |
insert_calculation_field | Insert calculation (SUM, AVERAGE, etc.) |
insert_date_field | Insert date/time field |
insert_page_field | Insert page number field |
insert_merge_field | Insert mail merge field |
insert_sequence_field | Insert auto-numbering sequence |
insert_content_control | Insert SDT content control |
Repeating Sections (1 tool)
| Tool | Description |
|---|
insert_repeating_section | Insert repeating section (Word 2012+) |
Advanced Features (9 tools)
| Tool | Description |
|---|
insert_toc | Insert table of contents |
insert_text_field | Insert form text field |
insert_checkbox | Insert form checkbox |
insert_dropdown | Insert form dropdown |
insert_equation | Insert math equation |
set_paragraph_border | Set paragraph border |
set_paragraph_shading | Set paragraph background color |
set_character_spacing | Set character spacing |
set_text_effect | Set text animation effect |
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
Comparison with Other Solutions
| Feature | Anthropic Word MCP | python-docx | docx npm | che-word-mcp |
|---|
| Language | Node.js | Python | Node.js | Swift |
| Backend | AppleScript | OOXML | OOXML | OOXML |
| Requires Word | Yes | No | No | No |
| Runtime | Node.js | Python | Node.js | None |
| Single Binary | No | No | No | Yes |
| Tools Count | ~10 | N/A | N/A | 146 |
| Images | Limited | Yes | Yes | Yes |
| Comments | No | Limited | Limited | Yes |
| Track Changes | No | No | No | Yes |
| TOC | No | Limited | No | Yes |
| Form Fields | No | No | No | Yes |
Performance
Benchmarks on Apple Silicon (M4 Max, 128GB RAM):
Read Performance
| File Size | Time |
|---|
| 40 KB (thesis outline) | 72 ms |
| 431 KB (complex document) | 31 ms |
Write Performance
| Operation | Content | Time |
|---|
| Basic write | Create + 3 paragraphs + Save | 19 ms |
| Complex document | Title + Paragraphs + Table + List | 21 ms |
| Bulk write | 50 paragraphs + Save | 28 ms |
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