io.github.kiki830621/che-word-mcp
Swift-native MCP server for Word (.docx) manipulation with 105 tools
Ask AI about io.github.kiki830621/che-word-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.kiki830621/che-word-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- 234 MCP Tools: Comprehensive document manipulation across documents, tables, hyperlinks, headers, sections, styles, numbering, content controls, comments, footnotes, equations, fields, and Track Changes
- Office.js OOXML Roadmap P0 = 100%: All eight P0 sub-issues closed (umbrella #43). Surface coverage is now competitive with Office.js for the read/write side of every P0 capability.
- Round-trip silent corruption closed (v3.13.5, #56): 5 sub-stack-completion rounds (R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4) closed 30 findings (16 P0 + 21 P1) across rounds 4-8 of 6-AI cross-verification. Bumps
ooxml-swiftto v0.19.5 (v0.19.4 held back per verify-gate). No MCP source changes β fix architecture lives entirely inooxml-swift. Round 4 walker symmetry across headers/footers/footnotes/endnotes (accept_revision/reject_revision/get_hyperlinks/replace_textreach all parts). Round 5 per-container relationships round-trip (update_hyperlinkURL sync targets owning part rels). Round 6delete_hyperlinkmirror + container<w:tbl>capture preserved. Round 7reject_revisiontyped clearMarker (file/API state convergence). Round 8accept_revisiontyped clearMarker (mirror) + matrix-pin asymmetry-guard removal +Document.repairContainerFileNamesmarksdocument.xml.rels+[Content_Types].xmldirty. Convergence: Devil's Advocate wrote 5 adversarial tests targeting the convergence-cycle pattern; all PASSED. See closing summary and v3.13.5 release notes. - Programmatic Track Changes (v3.12.0+, #45): Generate Word-native reviewable redlines via
insert_text_as_revision/delete_text_as_revision/move_text_as_revision, plusas_revision: trueflag onformat_text/set_paragraph_format. Emits<w:ins>/<w:del>/<w:moveFrom>/<w:moveTo>/<w:rPrChange>/<w:pPrChange>markup. Side-effect contract:as_revision: truerequires track changes enabled; throwstrack_changes_not_enabledotherwise (no silent auto-enable). Author resolution: explicit arg βrevisions.settings.authorβ"Unknown". - Tables / Hyperlinks / Headers extensions (v3.11.0+, #49 #50 #51): 16 new tools β table conditional styles (10 region types) / nested tables (max 5 deep) / explicit layout / table indent; three typed hyperlinks (URL / bookmark / email); even/odd header toggle / link-to-previous /
get_section_header_map. - Styles + Numbering + Sections foundation (v3.10.0+, #46 #47 #48): 19 new tools + 6 extended args β
get_style_inheritance_chain,link_styles,set_latent_styles,add_style_name_alias, full Numbering CRUD lifecycle (definitions / overrides / list continuity / GC), section vertical alignment / page-number format / break-type / title-page distinction / per-section header references. - Content Controls (SDT) read/write (v3.9.0+, #44): 7 new tools covering 12-type discrimination (richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem). Nested SDT trees, deterministic max+1 SDT id allocator,
keep_contentunwrap on delete, whitelist-validated XML replacement. - Save Durability Stack (v3.5.3+): atomic-rename save (#36), actor-based concurrency safety (#39),
keep_bakopt-in rollback (#38),autosave_everyDesign B pre-mutation snapshot with explicitrecover_from_autosave(#37, #40 v3.7.0). Defaultautosave_every: 1(every mutation snapshots prior state). Passautosave_every: 0to opt out. - Dual-Mode Access: Direct Mode (read-only, one step via
source_path) and Session Mode (full lifecycle viadoc_id) - True Byte-preservation Round-trip Fidelity (v3.5.0+):
save_documentoverlay mode usesWordDocument.modifiedPartsdirty tracking β untouched typed parts (document.xml,styles.xml,fontTable.xml,header*.xml,footer*.xml,comments.xml,footnotes.xml,endnotes.xml) and unknown parts (theme/,webSettings.xml,people.xml,commentsExtended/Extensible/Ids,glossary/,customXml/) byte-for-byte preserved. NTPU thesis no-opsave_documentround-trip retains 13 fontTable entries + 6 distinct headers + 4 footers + three-segment PAGE field +<w15:presenceInfo>identity. - Theme + Header/Footer/Watermark CRUD (v3.3.0+):
word/theme/theme1.xmlediting, header/footer enumeration + deletion, watermark VML detection. NTPU thesis Chinese font fix path:update_theme_fonts({ minor: { ea: "DFKai-SB" } }). - Comment Threads + People + Notes Update + Web Settings (v3.4.0+): 13 tools for collaborative comment metadata,
people.xmlauthor records (dual identity: GUID + legacy author), in-place endnote/footnote editing (preserves IDs),webSettings.xmlconfiguration. - Full LaTeX Subset for
insert_equation(v3.2.0+): Delegated tolatex-math-swift. Supports\frac,\sqrt,\hat/\bar/\tildeaccents,\left/\rightdelimiters,\sum/\int/\prodn-ary with bounds, function names, limits,\text{}, all Greek letters (including\varepsilonvariants), and common operators. - Text-Anchor Insertion: Insert captions / images relative to matched text (
after_text/before_text), no pre-search call required - Batch Operations:
replace_text_batch/search_text_batchcollapse N round-trips into one - Session State API: SHA256 + mtime-based disk drift detection,
revert_to_disk/reload_from_disk/check_disk_drift - Structural Readback:
list_captions/list_equations/update_all_fields(F9-equivalent) for manuscript review workflows - Cross-platform: Works on macOS (universal binary
x86_64 + arm64since v3.5.1)
Version History
| Version | Date | Changes |
|---|---|---|
| v3.13.5 | 2026-04-27 | R5 stack-completion (closes #56 silent corruption). Bumps ooxml-swift v0.19.3 β v0.19.5 (v0.19.4 held back per verify-gate). 30 findings closed (16 P0 + 21 P1) across 5 sub-stacks (R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4) and rounds 4-8 of 6-AI cross-verification. Round 4 walker symmetry across headers/footers/footnotes/endnotes (accept_revision / reject_revision / get_hyperlinks / replace_text reach all parts). Round 5 per-container relationships round-trip (update_hyperlink URL sync targets owning part rels). Round 6 delete_hyperlink mirror + container <w:tbl> capture preserved. Round 7 reject_revision typed clearMarker (file/API state convergence). Round 8 accept_revision typed clearMarker (mirror) + matrix-pin asymmetry-guard removal + repairContainerFileNames rels-dirty. Convergence: Devil's Advocate wrote 5 adversarial tests targeting the convergence-cycle pattern; all PASSED. No che-word-mcp source changes β entire fix architecture in ooxml-swift. See closing summary. |
| v3.13.4 | 2026-04-26 | (skipped β held back per verify-gate). R3 stack content rolled into v3.13.5. |
| v3.13.3 | 2026-04-26 | Bumps ooxml-swift v0.19.2 β v0.19.3. Closes 8 P0 + 3 must-fix P1 from #56 round-2 verify (Hyperlink API path visual-style restoration / tgtFrame / docLocation Reader filter / ordered children source-order preservation; sort-path contentControls + commentIds / footnoteIds / endnoteIds / hasPageBreak emission; non-text wrapper preservation; nested hyperlink/SDT/fieldSimple round-trip; nextBookmarkId calibration; bookmark wrap-around restoration). No source changes. |
| v3.13.2 | 2026-04-26 | Bumps ooxml-swift v0.19.1 β v0.19.2. Closes 4 blocking findings from #56 round-1 verify (F1 Hyperlink.toXML() emits Reader-collected runs/rawAttributes/rawChildren; F2 add_bookmark/delete_bookmark sync bookmarkMarkers; F3 ins/del/moveFrom/moveTo round-trip preserves position+revisionId+wrapper; F4 namespace preservation extends from document.xml to header/footer/footnote/endnote). No source changes. |
| v3.13.1 | 2026-04-25 | pPr double-emission silent regression on sort-by-position round-trip β hot-fix (ooxml-swift v0.19.1). |
| v3.13.0 | 2026-04-25 | document.xml lossless round-trip + tool-mediated wrapper edits (closes #56 P0). Hybrid model preserves namespace map (34 xmlns), bookmarks, structural wrappers (<w:hyperlink> / <w:fldSimple> / <mc:AlternateContent>). |
| v3.12.0 | 2026-04-25 | Programmatic Track Changes generation (closes #45) β 3 new tools (insert_text_as_revision / delete_text_as_revision / move_text_as_revision) + as_revision flag on format_text / set_paragraph_format. Emits <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> markup. |
| v3.11.0 | 2026-04-25 | Tables / Hyperlinks / Headers extensions (closes #49 #50 #51) β 16 new tools: table conditional styles (10 region types) / nested tables (max 5 deep) / explicit layout / table indent; three typed hyperlinks (URL / bookmark / email); even/odd header toggle / link-to-previous / get_section_header_map. |
| v3.10.0 | 2026-04-24 | Styles + Numbering + Sections foundation (closes #46 #47 #48) β 19 new tools + 6 extended args. get_style_inheritance_chain, link_styles, set_latent_styles, add_style_name_alias; full Numbering CRUD lifecycle; section vertical alignment / page-number format / break-type / title-page distinct / per-section header refs. |
| v3.9.0 | 2026-04-24 | Content Controls (SDT) read/write (closes #44) β 7 new tools, 12-type discrimination (richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem). Nested SDT trees, deterministic id allocator, keep_content unwrap, whitelist-validated XML replacement. |
| v3.8.0 | 2026-04-24 | Header/footer raw-element preservation + counter-isolation flag (closes #52). |
| v3.7.2 | 2026-04-24 | 3-issue bundle from #42 verification (closes #53, #54, #55 path traversal hardening). |
| v3.7.1 | 2026-04-24 | update_all_fields no longer strips headers/footers (closes #42). |
| v3.7.0 | 2026-04-24 | Insert crash hardening + autosave Design B (closes #40, #41). v3.6.0 shipped autosave_every Design A (post-mutation counter) which couldn't preserve K-1 mutations on crash at K when K%Nβ 0. v3.7.0 switches to Design B (snapshot fires at the START of every mutating handler before the mutation runs); default autosave_every flipped from 0 to 1 (every mutation snapshots prior state). Pass autosave_every: 0 to opt out. BREAKING (effective): callers who relied on Design A semantics or default disabled. Also adds Phase A CHE_WORD_MCP_LOG_LEVEL=debug structured logging gate for #41 investigation. Built on ooxml-swift 0.13.3 which kills DocxReader.concurrentPerform (parsing determinism prerequisite for recover_from_autosave) and refactors nextImageRelationshipId to use the rId allocator. Migration from v3.6.0: code passing autosave_every: 0 explicitly is unaffected; code that omitted the arg now gets 1 (full safety) β to restore v3.6.0 disabled-by-default behavior, add autosave_every: 0 to open_document calls. |
| v3.6.0 | 2026-04-23 | Autosave + checkpoint + recover_from_autosave (closes #37). open_document gains autosave_every: Int = 0 parameter β when N > 0, every Nth mutation triggers a checkpoint write to <source>.autosave.docx (separate file, NOT eager-save to source). New tools: checkpoint(doc_id, path?) for manual snapshot, recover_from_autosave(doc_id, discard_changes?) to replace in-memory state with autosave bytes. get_session_state adds autosave_detected + autosave_path fields. Successful save_document / finalize_document cleans up <source>.autosave.docx. Phase 4 of save-durability-stack SDD. |
| v3.5.5 | 2026-04-23 | keep_bak opt-in for rollback escape hatch (closes #38). save_document gains optional keep_bak: Bool = false; when true and target exists, server renames target β <path>.bak BEFORE atomic-rename save (single slot, overwrites prior .bak). User can mv <path>.bak <path> to roll back if a future save ships silent OOXML damage. .bak lives at server layer NOT ooxml-swift β macdoc CLI users don't get unwanted .bak files. Phase 3 of save-durability-stack SDD. |
| v3.5.4 | 2026-04-23 | class WordMCPServer β actor WordMCPServer (closes #39). 8 mutable session state dictionaries become actor-isolated; compiler enforces every cross-actor access via await. Eliminates the Dictionary hash-table corruption race that pre-v3.5.4 12-parallel insert_image_from_path calls triggered. Phase 2 of save-durability-stack SDD. |
| v3.5.3 | 2026-04-23 | Atomic-rename save (closes #36). Bumps to ooxml-swift 0.13.2 which refactors DocxWriter.write to write <url>.tmp.<UUID> + fsync + replaceItemAt. Any throw or process kill mid-write leaves the original byte-preserved (POSIX rename(2) is kernel-atomic; cross-volume falls back to copy+delete). 397/397 ooxml-swift tests pass; concurrent-observer regression test added. Phase 1 of save-durability-stack SDD. |
| v3.5.2 | 2026-04-23 | Rels overlay merge (closes #35) β Reader-loaded NTPU thesis no-op save_document round-trip now preserves theme / webSettings / people / customXml / commentsExtended / commentsIds rels. v3.5.0/v3.5.1 fixed the parts layer; v3.5.2 fixes the rels layer. No che-word-mcp source change β fix entirely in ooxml-swift v0.13.1 (RelationshipsOverlay + relationship-driven extractImages). |
| v3.5.1 | 2026-04-23 | Universal binary (x86_64 + arm64) β restores Intel Mac compatibility. v3.5.0 was arm64-only because release-build skipped the documented lipo -create step. No source changes β drop-in replacement. |
| v3.5.0 | 2026-04-23 | True byte-preservation via dirty tracking (closes #23 round-2 + #32 #33 #34). Reader-loaded NTPU theses survive no-op save_document round-trip with all 13 fontTable + 6 distinct headers + 4 footers + three-segment PAGE field + <w15:presenceInfo> identity preserved. Built on ooxml-swift 0.13.0 (modifiedParts: Set<String> + Header.originalFileName + overlay-mode skip-when-not-dirty). list_people returns dual identity: person_id (GUID, stable across rename) + display_name_id (= author legacy). |
| v3.4.0 | 2026-04-23 | Phase 2B + 2C combined (closes #24 #25 #29 #30 #31): comment threads (list_comment_threads / get_comment_thread / sync_extended_comments), people (list_people / add_person / update_person / delete_person), notes update (get_endnote / update_endnote / get_footnote / update_footnote β preserves note IDs), web settings (get_web_settings / update_web_settings). 13 new MCP tools. |
| v3.3.0 | 2026-04-23 | Phase 2A (closes #26 #27 #28): theme tools (get_theme / update_theme_fonts / update_theme_color / set_theme), headers (list_headers / get_header / delete_header), watermarks (list_watermarks / get_watermark), footers (list_footers / get_footer / delete_footer). 12 new MCP tools. Bumped to ooxml-swift 0.12.x for preserve-by-default round-trip. |
| v3.2.0 | 2026-04-23 | insert_equation LaTeX parser delegated to latex-math-swift (closes #22). Full LaTeX subset: \frac, \sqrt, \hat/\bar/\tilde, \left/\right, \sum/\int/\prod with bounds, \ln/\sin/\cos/\tan/\log/\exp/\max/\min/\det, \sup/\inf/\lim, \text{}, all Greek letters (incl. \varepsilon variants), common operators. 18 econometrics fixture equations now all parse. Adds MathAccent via ooxml-swift 0.11.0. |
| v3.1.0 | 2026-04-22 | 9 readback tools: Caption CRUD (list_captions / get_caption / update_caption / delete_caption), update_all_fields (F9-equivalent SEQ recount), Equation CRUD (list_equations / get_equation / update_equation / delete_equation). Built on new ooxml-swift 0.10.0 FieldParser + OMMLParser. |
| v3.0.0 | 2026-04-22 | BREAKING: session state API. New tools get_session_state / revert_to_disk / reload_from_disk / check_disk_drift. open_document track_changes default flipped from true to false. close_document dirty-check now returns E_DIRTY_DOC text response with recovery options (save_document / discard_changes: true / finalize_document). |
| v2.3.0 | 2026-04-22 | Text-anchor compound tool β insert_caption / insert_image_from_path accept after_text / before_text / text_instance. Eliminates the search_text + insert_* two-call pattern (~50% RPC reduction for thesis caption workflows). |
| v2.2.0 | 2026-04-22 | Batch API β replace_text_batch (sequential, single save at end, dry_run/stop_on_first_failure flags) + search_text_batch (aggregated multi-query response, Direct + Session Mode). |
| v2.1.0 | 2026-04-22 | Expose v2.0.0 params via inputSchema β schemas for insert_caption / insert_equation / insert_image_from_path / replace_text now advertise new params (Chinese labels, components, into_table_cell, scope, regex). |
| v2.0.0 | 2026-04-22 | BREAKING: word-mcp-insertion-primitives Spectra change. Real OOXML SEQ fields (was literal text), OMML MathComponent AST (was string substitution), auto-aspect image sizing + table-cell target, cross-run-safe replace_text with scope + regex backreferences. |
| v1.19.0 | 2026-04-15 | Manuscript review markdown export: export_revision_summary_markdown / compare_documents_markdown / export_comment_threads_markdown. BREAKING: get_revisions + compare_documents full_text param replaced by summarize (inverted default). |
| v1.18.0 | 2026-04-14 | Fix get_revisions hardcoded 30-char truncation (bug since v1.2.0); add full_text opt-in. |
| 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 |
Quick Start
For Claude Desktop
Option A: MCPB One-Click Install (Recommended)
Download the latest .mcpb file from Releases and double-click to install.
Option B: Manual Configuration
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"che-word-mcp": {
"command": "/usr/local/bin/CheWordMCP"
}
}
}
For Claude Code (CLI)
Option A: Install as Plugin (Recommended)
The plugin bundles a version-aware wrapper that auto-downloads the binary on first use (and re-downloads whenever the plugin itself is updated β no swift build needed).
Two steps β register the marketplace once, then install the plugin:
# 1. Register the marketplace (one-time)
claude plugin marketplace add PsychQuant/psychquant-claude-plugins
# 2. Install the plugin
claude plugin install che-word-mcp@psychquant-claude-plugins
Inside Claude Code? The slash-command equivalents
/plugin marketplace add PsychQuant/psychquant-claude-pluginsand/plugin install che-word-mcp@psychquant-claude-pluginswork the same way.
Note: The plugin wraps the MCP binary with auto-download. If the binary is missing from
~/bin/CheWordMCP(or the sidecar~/bin/.CheWordMCP.versionis older than the plugin's pinned version), it will be downloaded from GitHub Releases on next invocation.
Option B: Install as standalone MCP
If you only need the MCP server without plugin features (slash commands, skills, SessionStart hooks):
# Create ~/bin if needed
mkdir -p ~/bin
# Download the latest release
curl -L https://github.com/PsychQuant/che-word-mcp/releases/latest/download/CheWordMCP -o ~/bin/CheWordMCP
chmod +x ~/bin/CheWordMCP
# Register with Claude Code
# --scope user : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# -- : separator between claude options and the command
claude mcp add --scope user --transport stdio che-word-mcp -- ~/bin/CheWordMCP
π‘ Tip: Install the binary into a local directory like
~/bin/. Avoid cloud-synced folders (Dropbox, iCloud, OneDrive) β their sync operations can break MCP connections.
Build from Source (Optional)
Use this only if you want to track main or contribute patches.
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
# Install
cp .build/release/CheWordMCP ~/bin/
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" }
19 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, estimate_paragraph_for_page |
| 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_pathanddoc_id. If you already have a document open, usedoc_idto 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 (234 Total)
Paragraph Index Conventions
paragraph_index / index are historical parameter names and do not always
count the same OOXML surface. Different insert / mutate / readback tools
use different conventions β there is no universal default to assume.
Three coordinate systems coexist:
body.children insertion index (used by some inserts), top-level paragraph
ordinal (used by most mutate operations and inline equation insertion),
and get_paragraphs readback order (for inspection). See
docs/paragraph-index-conventions.md
for the per-tool inventory before reusing an index across tools.
Document Management (6 tools)
| Tool | Description |
|---|---|
create_document | Create a new Word document |
open_document | Open an existing .docx file (track_changes default false since v3.0.0) |
save_document | Save document to .docx file |
close_document | Close an open document (pass discard_changes: true to drop dirty edits) |
finalize_document | Save and close in one guarded step |
list_open_documents | List all open documents |
Session State API (5 tools, v3.0.0+)
| Tool | Description |
|---|---|
get_session_state | Snapshot { source_path, disk_hash_hex, disk_mtime_iso8601, is_dirty, track_changes_enabled } |
get_document_session_state | Legacy session snapshot (preserved for backward compat) |
revert_to_disk | Re-read source path, discard in-memory edits (destructive-by-design) |
reload_from_disk | Cooperative reload; requires force: true on dirty doc |
check_disk_drift | Informational β returns { drifted, disk_mtime, stored_mtime, disk_hash_matches } |
Content Operations (9 tools)
| Tool | Description |
|---|---|
get_text | Get plain text content |
get_paragraphs | Get all paragraphs with formatting |
estimate_paragraph_for_page | v3.18.0+ β estimate a Word UI page number to a get_paragraphs candidate range (heuristic JSON with confidence + warning) |
insert_paragraph | Insert a new paragraph |
update_paragraph | Update paragraph content |
delete_paragraph | Delete a paragraph |
replace_text | Cross-run-safe find & replace with scope (body|all) + regex + $1..$N backreferences |
replace_text_batch | v2.2.0 β sequential N-replacement batch, single save at end, dry_run / stop_on_first_failure |
search_text_batch | v2.2.0 β aggregated multi-query search, works in Direct + Session Mode |
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 (15 tools, v3.11.0+ extensions #49)
Core (6):
| 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 |
Row / column / cell (8):
| Tool | Description |
|---|---|
add_row_to_table, delete_row_from_table | Row management |
add_column_to_table, delete_column_from_table | Column management |
set_cell_width, set_cell_vertical_alignment | Cell sizing + alignment |
set_row_height, set_table_alignment | Row height + table alignment |
Advanced (5, v3.11.0):
| Tool | Description |
|---|---|
set_table_conditional_style | Apply firstRow / lastRow / bandedRows etc. (10 region types) via <w:tblStylePr> |
insert_nested_table | Insert table-in-cell, depth-limited to 5 (throws nested_too_deep) |
set_table_layout | Switch fixed / autofit |
set_header_row | Mark row as <w:tblHeader/> for repeat-on-page-break |
set_table_indent | Table-level left indent (<w:tblInd>) |
Style Management (8 tools + 6 extended args, v3.10.0+ #48)
Core (4):
| Tool | Description |
|---|---|
list_styles | List all available styles (Direct Mode supported) |
create_style | Create custom style β extended with 6 v3.10 args: based_on, linked_style_id, next_style_id, q_format, hidden, semi_hidden |
update_style | Update style definition β same 6 extended args |
delete_style | Delete custom style |
Inheritance + linkage (4, v3.10.0):
| Tool | Description |
|---|---|
get_style_inheritance_chain | Traverse basedOn chain upward to root with cycle detection |
link_styles | Bidirectional <w:link> between paragraph and character style pair |
set_latent_styles | Control Quick Style Gallery defaults via <w:latentStyles> block |
add_style_name_alias | Localized <w:name> alias per BCP 47 lang code |
Numbering / Lists (12 tools, v3.10.0+ definition lifecycle #46)
Inline list creation (4):
| Tool | Description |
|---|---|
insert_bullet_list | Insert bullet list |
insert_numbered_list | Insert numbered list |
set_list_level | Set list indentation level |
set_outline_level | Set paragraph outline level (TOC inclusion) |
Definition CRUD (8, v3.10.0):
| Tool | Description |
|---|---|
list_numbering_definitions | Enumerate every abstractNum + num pair |
get_numbering_definition | Fetch single num by id |
create_numbering_definition | New abstractNum + paired num (max 9 levels) |
override_numbering_level | <w:lvlOverride> for per-level start values |
assign_numbering_to_paragraph | <w:numPr> attachment by paragraph index |
continue_list | Resume numbering across paragraphs |
start_new_list | Reset numbering to start |
gc_orphan_numbering | Sweep unreferenced num definitions (abstractNums preserved) |
Sections / Page Setup (12 tools, v3.10.0+ extensions #47)
Basic page setup (5):
| 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 |
Section properties (7, v3.10.0):
| Tool | Description |
|---|---|
get_all_sections | Return SectionInfo array per section in document order |
set_section_break_type | nextPage / continuous / evenPage / oddPage |
set_section_vertical_alignment | <w:vAlign> for cover pages |
set_page_number_format | <w:pgNumType w:fmt> for Roman numerals etc. |
set_line_numbers_for_section | <w:lnNumType> for legal documents |
set_title_page_distinct | Toggle <w:titlePg/> per section |
set_section_header_footer_references | Assign per-type rId (default/first/even) |
Headers & Footers (17 tools, v3.11.0+ even/odd + section map #51)
Write tools (5):
| Tool | Description |
|---|---|
add_header | Add header content (uses RelationshipIdAllocator since v3.3.0+ β collision-free rIds in overlay mode) |
update_header | Update header content (preserves filename + rId; in-place tempDir overwrite) |
add_footer | Add footer content |
update_footer | Update footer content |
insert_page_number | Insert page number field |
Read + delete tools (8, v3.3.0+, closes #26 #27):
| Tool | Description |
|---|---|
list_headers | Enumerate header parts with type (default/first/even) + section_id + has_watermark |
get_header | Read text + full XML + watermark structure |
delete_header | Remove typed model entry + tempDir file + Relationship + Content_Types Override |
list_watermarks | Scan all headers for VML PowerPlusWaterMarkObject shapes (text or image) |
get_watermark | Single-header watermark detail (returns null if no watermark) |
list_footers | Enumerate footer parts with type + section_id + has_page_number |
get_footer | Read text + XML + parsed field structure (PAGE / NUMPAGES / REF / STYLEREF) |
delete_footer | Symmetric with delete_header |
Even/odd + section linkage (4, v3.11.0):
| Tool | Description |
|---|---|
enable_even_odd_headers | Toggle document-level <w:evenAndOddHeaders/> flag |
link_section_header_to_previous | Word-compat clone semantics |
unlink_section_header_from_previous | Symmetric unlink |
get_section_header_map | Return per-section header / footer file assignments |
Theme Editing (4 tools, v3.3.0+, closes #28)
| Tool | Description |
|---|---|
get_theme | Read major/minor font slots (latin/ea/cs) + color scheme (accent1-6, hyperlink, followedHyperlink) from word/theme/theme1.xml |
update_theme_fonts | Partial-update font slots β e.g. { minor: { ea: "DFKai-SB" } } for NTPU thesis Chinese font fix |
update_theme_color | Slot-named hex color update with validation (rejects invalid slot + non-6-char-hex) |
set_theme | Low-level escape hatch β replace theme1.xml verbatim (validates <a:theme> root + well-formed XML) |
Images (7 tools)
| Tool | Description |
|---|---|
insert_image | Insert inline image (PNG, JPEG) |
insert_image_from_path | v2.0.0+ β width/height optional (auto-aspect via ImageDimensions.detect), supports into_table_cell + after_text / before_text anchors |
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 |
Captions (5 tools)
| Tool | Description |
|---|---|
insert_caption | v2.0.0+ β real OOXML SEQ field (not literal text). Accepts English + Chinese labels (Figure/Table/Equation/ε/葨/ε
¬εΌ), 5-way anchor (paragraph_index / after_image_id / after_table_index / after_text / before_text), optional STYLEREF chapter number prefix |
list_captions | v3.1.0 β enumerate caption paragraphs with label / sequence_number / caption_text / paragraph_index |
get_caption | v3.1.0 β detailed single caption info including optional chapter_number from STYLEREF |
update_caption | v3.1.0 β modify caption text or label without breaking the SEQ field structure |
delete_caption | v3.1.0 β remove caption paragraph |
Equations (5 tools)
| Tool | Description |
|---|---|
insert_equation | v2.0.0+ β emits structurally correct OMML via MathComponent AST (9 types). Primary: components: tree; fallback: latex: subset (\frac, \sqrt, x^{y}, Greek, β/β«/β) |
list_equations | v3.1.0 β enumerate <m:oMath> runs with display_mode flag |
get_equation | v3.1.0 β detailed single equation info with component summary |
update_equation | v3.1.0 β replace target equation's components tree |
delete_equation | v3.1.0 β remove equation run or empty paragraph |
Export (5 tools)
| Tool | Description |
|---|---|
export_text | Export as plain text |
export_markdown | Export as Markdown (uses embedded word-to-md-swift) |
export_revision_summary_markdown | v1.19.0 β per-document revision timeline for manuscript review |
compare_documents_markdown | v1.19.0 β multi-document cumulative revision timeline |
export_comment_threads_markdown | v1.19.0 β comment threading with author alias normalization |
Hyperlinks & Bookmarks (10 tools, v3.11.0+ typed variants #50)
Generic + bookmarks (7):
| Tool | Description |
|---|---|
insert_hyperlink | Insert external hyperlink |
insert_internal_link | Insert link to bookmark |
insert_cross_reference | Insert cross-reference |
update_hyperlink | Update hyperlink |
delete_hyperlink | Delete hyperlink |
insert_bookmark | Insert bookmark |
delete_bookmark | Delete bookmark |
Typed hyperlinks (3, v3.11.0, auto-create Hyperlink character style):
| Tool | Description |
|---|---|
insert_url_hyperlink | External URL with optional tooltip + history flag |
insert_bookmark_hyperlink | Internal anchor link (w:anchor, no rId) |
insert_email_hyperlink | mailto: with optional URL-encoded subject |
Comments & Revisions (13 tools)
Comment write + read (7):
| 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 |
list_comment_threads | v3.4.0 β enumerate threads (root_comment_id + replies + resolved + durable_id) using typed Comment.parentId from commentsExtended.xml |
Comment thread tools (2, v3.4.0+, closes #29):
| Tool | Description |
|---|---|
get_comment_thread | Read root + walk children for full reply tree |
sync_extended_comments | Report typed comment count for triplet sync planning |
Revision tracking β accept/reject side (7):
| Tool | Description |
|---|---|
enable_track_changes | Enable track changes (sets revisions.settings.author for default author resolution) |
disable_track_changes | Disable track changes |
get_revisions | Enumerate all revisions (Direct Mode supported) |
accept_revision | Accept revision by id |
reject_revision | Reject revision by id |
accept_all_revisions | Bulk accept |
reject_all_revisions | Bulk reject |
Revision tracking β programmatic write side (3, v3.12.0 #45):
| Tool | Description |
|---|---|
insert_text_as_revision | Insert text wrapped in <w:ins> revision markup. Splits straddling runs at position (preserves prior + post text + formatting). Args: doc_id, paragraph_index, position, text, optional author, date. |
delete_text_as_revision | Mark [start, end) runs with <w:del> and substitute <w:t> β <w:delText>. Single-paragraph only (cross-paragraph delete out of scope). |
move_text_as_revision | Emit paired <w:moveFrom> / <w:moveTo> with adjacent revision ids. Single-paragraph moves rejected (callers should use delete + insert). |
Plus 2 extended args on existing tools (additive, default false):
format_textgainsas_revision: boolβ produces<w:rPrChange>revision instead of silent format mutation. Also acceptsrun_index,author,date.set_paragraph_formatgainsas_revision: boolβ produces<w:pPrChange>revision.
Side-effect contract: as_revision: true requires enable_track_changes to have been called. Disabled track changes throws track_changes_not_enabled instead of silent auto-enable. Author resolution chain: explicit non-empty author arg β revisions.settings.author β literal "Unknown".
People β Comment Authors (4 tools, v3.4.0+, closes #30)
| Tool | Description |
|---|---|
list_people | Parse <w15:person> entries from word/people.xml |
add_person | Add new entry; auto-create people.xml part when absent; duplicate-name _2 suffix |
update_person | Update display_name (author attribute swap) |
delete_person | Remove entry; report comments_orphaned count |
Footnotes & Endnotes (10 tools)
Write + delete (4):
| Tool | Description |
|---|---|
insert_footnote | Insert footnote |
delete_footnote | Delete footnote |
insert_endnote | Insert endnote |
delete_endnote | Delete endnote |
List + read + update (6, v3.4.0+, closes #24 #25):
| Tool | Description |
|---|---|
list_footnotes | Direct Mode supported |
list_endnotes | Direct Mode supported |
get_footnote | Read text + runs by integer ID |
update_footnote | In-place text replacement, preserves footnote_id (cross-references stay valid) |
get_endnote | Read text + runs by integer ID |
update_endnote | In-place text replacement, preserves endnote_id |
Web Settings (2 tools, v3.4.0+, closes #31)
| Tool | Description |
|---|---|
get_web_settings | Parse word/webSettings.xml flag elements (relyOnVML, optimizeForBrowser, allowPNG, doNotSaveAsSingleFile); returns { error: "no webSettings part" } when absent |
update_web_settings | Partial update by key; auto-create part if absent |
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 |
update_all_fields | v3.1.0 β F9-equivalent SEQ recount across body + headers + footers + footnotes + endnotes. Supports chapter-reset when pStyle=="Heading N" matches SEQ resetLevel |
Content Controls / SDT (10 tools, v3.9.0+ full read/write #44)
Insert + form helpers (5):
| Tool | Description |
|---|---|
insert_content_control | 12-type discrimination (richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection (rejected β use insert_repeating_section) / repeatingSectionItem). Optional args: list_items (required for dropDown/comboBox), date_format, lock_type. |
insert_repeating_section | Insert repeating section (Word 2012+); accepts allow_insert_delete_sections: bool (default true) |
insert_checkbox | Insert checkbox SDT |
insert_dropdown | Insert dropdown SDT |
insert_text_field | Insert plain-text SDT |
Read tools (3):
| Tool | Description |
|---|---|
list_content_controls | Enumerate every SDT, flat (default) or nested tree mode (Direct Mode supported) |
get_content_control | Fetch single SDT by id, tag, or alias. Returns full metadata + <w:sdtContent> XML. Surfaces not_found / multiple_matches errors. |
list_repeating_section_items | Enumerate items inside a repeating-section SDT in document order |
Modify tools (4):
| Tool | Description |
|---|---|
update_content_control_text | Replace text content of plainText / richText / date / bibliography / citation SDTs. Preserves <w:sdtPr> byte-identical. Returns unsupported_type for picture / dropdown / combo / checkbox / group / repeatingSection. |
replace_content_control_content | Replace full <w:sdtContent> XML with whitelist validation (rejects input containing <w:sdt>, <w:body>, <w:sectPr>, or XML declaration) |
delete_content_control | Remove SDT, optionally unwrapping children (keep_content: true default) |
update_repeating_section_item | Replace text of single item by index (out_of_bounds for invalid index) |
SDT id allocation uses deterministic max+1 (was random in pre-v3.9.0). list_custom_xml_parts ships as empty-list stub for forward compat (real impl in che-word-mcp-customxml-databinding Change B).
Advanced Features (10 tools)
| Tool | Description |
|---|---|
insert_toc | Insert table of contents |
insert_table_of_figures | Insert table of figures |
insert_index, insert_index_entry | Index generation |
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 |
insert_horizontal_line, insert_drop_cap, insert_symbol | Decorative elements |
Note: The counts above cover key tool categories. Total surface is 233 tools as of v3.13.5 including Document Comparison, Track Changes (read + programmatic write side via
<w:ins>/<w:del>/<w:moveFrom>/<w:moveTo>/<w:rPrChange>/<w:pPrChange>), Content Controls (12-type SDT discrimination), Field Codes, Theme Editing, Header/Footer/Watermark CRUD with even/odd + section linkage, Comment Threads + People (dual identity), Notes Update, Web Settings, Styles (inheritance + linkage + latent + alias), Numbering (full definition lifecycle), Sections (vertical alignment + page-number format + title-page distinct + per-section refs), Tables (conditional / nested / layout / indent), Hyperlinks (typed url/bookmark/email), and Formatting helpers (withas_revisionflag). Run the server and calltools/listfor the complete, authoritative set.
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.12.0+) β Model Context Protocol implementation
- ooxml-swift (v0.12.0+) β OOXML parsing + preserve-by-default round-trip architecture (PreservedArchive, RelationshipIdAllocator, ContentTypesOverlay),
FieldParser,OMMLParser,updateAllFields(),MathAccent - latex-math-swift (v0.1.0+) β LaTeX subset β OMML
MathComponentAST parser (used byinsert_equationv3.2.0+) - markdown-swift (v0.2.0+) β Markdown generation
- word-to-md-swift (v0.4.0+) β Word to Markdown conversion
Developer Notes β Real-World Fixture Testing
Tests/CheWordMCPTests/RealWorldDocxRoundTripSmokeTests.swift validates the
ooxml-swift Reader / Writer pair against real-world Word output (e.g., academic
theses, contracts) rather than synthesized fixtures. Drop confidential .docx
files into test-files/ (gitignored β they never reach version control), then:
cd mcp/che-word-mcp
swift test --filter RealWorldDocxRoundTripSmokeTests
Per-fixture assertions: xmllint --noout clean, bookmark / hyperlink /
fldSimple / AlternateContent count parity, SHA256 of concatenated <w:t>
content matches. The test silently XCTSkips when test-files/ is empty so
clean clones / CI do not false-fail. Mirrors the .note smoke pattern from
PsychQuant/macdoc#81.
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 | 233 |
| 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 (@PsychQuant)
Contributors
- @ildunari β session state management (v1.17.0)
Related Projects
- che-apple-mail-mcp - Apple Mail MCP server
- che-ical-mcp - macOS Calendar MCP server
