README.md
Swift-native MCP server for Microsoft Word document manipulation.
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.17.0 | 2026-03-11 | Session state management: dirty tracking, autosave, finalize_document, get_document_session_state, shutdown flush (contributed by @ildunari) |
| 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/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:
| 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 f
Tools (5)
get_textExtracts text content from a Word document.search_textSearches for a specific query within the document.export_markdownConverts a Word document to Markdown format.compare_documentsPerforms a server-side diff between two documents.open_documentOpens a document for session-based read/write operations.Configuration
claude_desktop_config.json
{"mcpServers": {"che-word-mcp": {"command": "/path/to/che-word-mcp/.build/release/CheWordMCP"}}}Try it
→Extract all the text from my project_proposal.docx file.
→Search for the term 'budget' in the document located at /documents/report.docx.
→Convert my meeting_notes.docx into a Markdown file.
→Compare the differences between version1.docx and version2.docx.
→List all images found in the document at /files/presentation.docx.