Provides tools for exporting Microsoft Word (.docx) documents to Markdown format, enabling high-quality content conversion and documentation workflows.
Directly manipulates Office Open XML (OOXML) structures to enable comprehensive document operations including text editing, table management, and style application without external dependencies.
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.
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-swift to v0.19.5 (v0.19.4 held back per verify-gate). No MCP source changes — fix architecture lives entirely in ooxml-swift. 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 + Document.repairContainerFileNames marks document.xml.rels + [Content_Types].xml dirty. 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, plus as_revision: true flag on format_text / set_paragraph_format. Emits <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> markup. Side-effect contract: as_revision: true requires track changes enabled; throws track_changes_not_enabled otherwise (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_content unwrap on delete, whitelist-validated XML replacement.
Save Durability Stack (v3.5.3+): atomic-rename save (#36), actor-based concurrency safety (#39), keep_bak opt-in rollback (#38), autosave_every Design B pre-mutation snapshot with explicit recover_from_autosave (#37, #40 v3.7.0). Default autosave_every: 1 (every mutation snapshots prior state). Pass autosave_every: 0 to opt out.
Dual-Mode Access: Direct Mode (read-only, one step via source_path) and Session Mode (full lifecycle via doc_id)
True Byte-preservation Round-trip Fidelity (v3.5.0+): save_document overlay mode uses WordDocument.modifiedParts dirty 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-op save_document round-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.xml editing, 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.xml author records (dual identity: GUID + legacy author), in-place endnote/footnote editing (preserves IDs), webSettings.xml configuration.
Full LaTeX Subset for insert_equation (v3.2.0+): Delegated to latex-math-swift. Supports \frac, \sqrt, \hat/\bar/\tilde accents, \left/\right delimiters, \sum/\int/\prod n-ary with bounds, function names, limits, \text{}, all Greek letters (including \varepsilon variants), 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_batch collapse 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 + arm64 since v3.5.1)
Related MCP server: MCP-OPENAPI-DOCX
Version | Date | Changes |
v4.0.0 | 2026-08-19 |
|
v3.22.0 | 2026-07-18 | Self-produced docx upgrades to typed DSL (closes-via-idd #173, PR #174). Bumps ooxml-swift 1.4.0 → 1.5.0 (upstream ooxml-swift#85: transcoder-canonical authoring — stamped |
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 ( |
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 |
v3.13.1 | 2026-04-25 |
|
v3.13.0 | 2026-04-25 |
|
v3.12.0 | 2026-04-25 | Programmatic Track Changes generation (closes #45) — 3 new tools ( |
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 / |
v3.10.0 | 2026-04-24 | Styles + Numbering + Sections foundation (closes #46 #47 #48) — 19 new tools + 6 extended args. |
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, |
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 |
|
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 |
v3.6.0 | 2026-04-23 | Autosave + checkpoint + recover_from_autosave (closes #37). |
v3.5.5 | 2026-04-23 |
|
v3.5.4 | 2026-04-23 |
|
v3.5.3 | 2026-04-23 | Atomic-rename save (closes #36). Bumps to ooxml-swift 0.13.2 which refactors |
v3.5.2 | 2026-04-23 | Rels overlay merge (closes #35) — Reader-loaded NTPU thesis no-op |
v3.5.1 | 2026-04-23 | Universal binary ( |
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 |
v3.4.0 | 2026-04-23 | Phase 2B + 2C combined (closes #24 #25 #29 #30 #31): comment threads ( |
v3.3.0 | 2026-04-23 | Phase 2A (closes #26 #27 #28): theme tools ( |
v3.2.0 | 2026-04-23 |
|
v3.1.0 | 2026-04-22 | 9 readback tools: Caption CRUD ( |
v3.0.0 | 2026-04-22 | BREAKING: session state API. New tools |
v2.3.0 | 2026-04-22 | Text-anchor compound tool — |
v2.2.0 | 2026-04-22 | Batch API — |
v2.1.0 | 2026-04-22 | Expose v2.0.0 params via |
v2.0.0 | 2026-04-22 | BREAKING: |
v1.19.0 | 2026-04-15 | Manuscript review markdown export: |
v1.18.0 | 2026-04-14 | Fix |
v1.17.0 | 2026-03-11 | Session state management: dirty tracking, autosave, |
v1.16.0 | 2026-03-10 | Dual-Mode: 15 read-only tools now support |
v1.15.2 | 2026-03-07 | Improve |
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 |
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 |
|
v1.11.1 | 2026-02-28 | Fix |
v1.11.0 | 2026-02-28 |
|
v1.9.0 | 2026-02-28 |
|
v1.8.0 | 2026-02-03 | Remove hard diff limit, add |
v1.7.0 | 2026-02-03 | Add |
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 |
Download the latest .mcpb file from Releases and double-click to install.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"che-word-mcp": {
"command": "/usr/local/bin/CheWordMCP"
}
}
}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-pluginsInside 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.
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.
Use this only if you want to track main or contribute patches.
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/source_path) — Read-only, no statePass 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 |
|
List elements |
|
Properties |
|
Export |
|
doc_id) — Full read/write lifecycleCall 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.
Use che-word-mcp to read all images from ~/Documents/report.docxThe agent will automatically use Direct Mode (no need to open/close).
## 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 memorymkdir -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.mdparagraph_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.
Tool | Description |
| Create a new Word document |
| Open an existing .docx file (track_changes default |
| Save document to .docx file |
| Close an open document (pass |
| Save and close in one guarded step |
| List all open documents |
Tool | Description |
| Snapshot |
| Legacy session snapshot (preserved for backward compat) |
| Re-read source path, discard in-memory edits (destructive-by-design) |
| Cooperative reload; requires |
| Informational — returns |
Tool | Description |
| Get plain text content |
| Get all paragraphs with formatting |
| v3.18.0+ — estimate a Word UI page number to a |
| Insert a new paragraph |
| Update paragraph content |
| Delete a paragraph |
| Cross-run-safe find & replace with |
| v2.2.0 — sequential N-replacement batch, single save at end, |
| v2.2.0 — aggregated multi-query search, works in Direct + Session Mode |
Tool | Description |
| Apply text formatting (bold, italic, color, font) |
| Set paragraph formatting (alignment, spacing) |
| Apply built-in or custom styles |
Core (6):
Tool | Description |
| Insert a table with optional data |
| Get all tables information |
| Update cell content |
| Delete a table |
| Merge cells horizontally or vertically |
| Set table borders and shading |
Row / column / cell (8):
Tool | Description |
| Row management |
| Column management |
| Cell sizing + alignment |
| Row height + table alignment |
Advanced (5, v3.11.0):
Tool | Description |
| Apply firstRow / lastRow / bandedRows etc. (10 region types) via |
| Insert table-in-cell, depth-limited to 5 (throws |
| Switch fixed / autofit |
| Mark row as |
| Table-level left indent ( |
Core (4):
Tool | Description |
| List all available styles (Direct Mode supported) |
| Create custom style — extended with 6 v3.10 args: |
| Update style definition — same 6 extended args |
| Delete custom style |
Inheritance + linkage (4, v3.10.0):
Tool | Description |
| Traverse |
| Bidirectional |
| Control Quick Style Gallery defaults via |
| Localized |
Inline list creation (4):
Tool | Description |
| Insert bullet list |
| Insert numbered list |
| Set list indentation level |
| Set paragraph outline level (TOC inclusion) |
Definition CRUD (8, v3.10.0):
Tool | Description |
| Enumerate every abstractNum + num pair |
| Fetch single num by id |
| New abstractNum + paired num (max 9 levels) |
|
|
|
|
| Resume numbering across paragraphs |
| Reset numbering to start |
| Sweep unreferenced num definitions (abstractNums preserved) |
Basic page setup (5):
Tool | Description |
| Set page size (A4, Letter, etc.) |
| Set page margins |
| Set portrait or landscape |
| Insert page break |
| Insert section break |
Section properties (7, v3.10.0):
Tool | Description |
| Return SectionInfo array per section in document order |
|
|
|
|
|
|
|
|
| Toggle |
| Assign per-type rId (default/first/even) |
Write tools (5):
Tool | Description |
| Add header content (uses |
| Update header content (preserves filename + rId; in-place tempDir overwrite) |
| Add footer content |
| Update footer content |
| Insert page number field |
Read + delete tools (8, v3.3.0+, closes #26 #27):
Tool | Description |
| Enumerate header parts with type (default/first/even) + section_id + has_watermark |
| Read text + full XML + watermark structure |
| Remove typed model entry + tempDir file + Relationship + Content_Types Override |
| Scan all headers for VML |
| Single-header watermark detail (returns |
| Enumerate footer parts with type + section_id + has_page_number |
| Read text + XML + parsed field structure (PAGE / NUMPAGES / REF / STYLEREF) |
| Symmetric with delete_header |
Even/odd + section linkage (4, v3.11.0):
Tool | Description |
| Toggle document-level |
| Word-compat clone semantics |
| Symmetric unlink |
| Return per-section header / footer file assignments |
Tool | Description |
| Read major/minor font slots (latin/ea/cs) + color scheme (accent1-6, hyperlink, followedHyperlink) from |
| Partial-update font slots — e.g. |
| Slot-named hex color update with validation (rejects invalid slot + non-6-char-hex) |
| Low-level escape hatch — replace theme1.xml verbatim (validates |
Tool | Description |
| Insert inline image (PNG, JPEG) |
| v2.0.0+ — width/height optional (auto-aspect via |
| Insert floating image with text wrap |
| Update image properties |
| Delete image |
| List all images |
| Set image border and effects |
Tool | Description |
| v2.0.0+ — real OOXML SEQ field (not literal text). Accepts English + Chinese labels ( |
| v3.1.0 — enumerate caption paragraphs with label / sequence_number / caption_text / paragraph_index |
| v3.1.0 — detailed single caption info including optional |
| v3.1.0 — modify caption text or label without breaking the SEQ field structure |
| v3.1.0 — remove caption paragraph |
Tool | Description |
| v2.0.0+ — emits structurally correct OMML via |
| v3.1.0 — enumerate |
| v3.1.0 — detailed single equation info with component summary |
| v3.1.0 — replace target equation's components tree |
| v3.1.0 — remove equation run or empty paragraph |
Tool | Description |
| Export as plain text |
| Export as Markdown (uses embedded |
| v1.19.0 — per-document revision timeline for manuscript review |
| v1.19.0 — multi-document cumulative revision timeline |
| v1.19.0 — comment threading with author alias normalization |
Generic + bookmarks (7):
Tool | Description |
| Insert external hyperlink |
| Insert link to bookmark |
| Insert cross-reference |
| Update hyperlink |
| Delete hyperlink |
| Insert bookmark |
| Delete bookmark |
Typed hyperlinks (3, v3.11.0, auto-create Hyperlink character style):
Tool | Description |
| External URL with optional tooltip + history flag |
| Internal anchor link ( |
|
|
Comment write + read (7):
Tool | Description |
| Insert comment |
| Update comment text |
| Delete comment |
| List all comments |
| Reply to existing comment |
| Mark comment as resolved |
| v3.4.0 — enumerate threads (root_comment_id + replies + resolved + durable_id) using typed |
Comment thread tools (2, v3.4.0+, closes #29):
Tool | Description |
| Read root + walk children for full reply tree |
| Report typed comment count for triplet sync planning |
Revision tracking — accept/reject side (7):
Tool | Description |
| Enable track changes (sets |
| Disable track changes |
| Enumerate all revisions (Direct Mode supported) |
| Accept revision by id |
| Reject revision by id |
| Bulk accept |
| Bulk reject |
Revision tracking — programmatic write side (3, v3.12.0 #45):
Tool | Description |
| Insert text wrapped in |
| Mark |
| Emit paired |
Plus 2 extended args on existing tools (additive, default false):
format_text gains as_revision: bool — produces <w:rPrChange> revision instead of silent format mutation. Also accepts run_index, author, date.
set_paragraph_format gains as_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".
Tool | Description |
| Parse |
| Add new entry; auto-create |
| Update display_name (author attribute swap) |
| Remove entry; report |
Write + delete (4):
Tool | Description |
| Insert footnote |
| Delete footnote |
| Insert endnote |
| Delete endnote |
List + read + update (6, v3.4.0+, closes #24 #25):
Tool | Description |
| Direct Mode supported |
| Direct Mode supported |
| Read text + runs by integer ID |
| In-place text replacement, preserves footnote_id (cross-references stay valid) |
| Read text + runs by integer ID |
| In-place text replacement, preserves endnote_id |
Tool | Description |
| Parse |
| Partial update by key; auto-create part if absent |
Tool | Description |
| Insert IF conditional field |
| Insert calculation (SUM, AVERAGE, etc.) |
| Insert date/time field |
| Insert page number field |
| Insert mail merge field |
| Insert auto-numbering sequence |
| v3.1.0 — F9-equivalent SEQ recount across body + headers + footers + footnotes + endnotes. Supports chapter-reset when |
Insert + form helpers (5):
Tool | Description |
| 12-type discrimination ( |
| Insert repeating section (Word 2012+); accepts |
| Insert checkbox SDT |
| Insert dropdown SDT |
| Insert plain-text SDT |
Read tools (3):
Tool | Description |
| Enumerate every SDT, flat (default) or nested tree mode (Direct Mode supported) |
| Fetch single SDT by |
| Enumerate items inside a repeating-section SDT in document order |
Modify tools (4):
Tool | Description |
| Replace text content of plainText / richText / date / bibliography / citation SDTs. Preserves |
| Replace full |
| Remove SDT, optionally unwrapping children ( |
| Replace text of single item by 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).
Tool | Description |
| Insert table of contents |
| Insert table of figures |
| Index generation |
| Set paragraph border |
| Set paragraph background color |
| Set character spacing |
| Set text animation effect |
| 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.
Create a new Word document called "report" with:
- Title: "Quarterly Report"
- Heading: "Introduction"
- A paragraph explaining the report purpose
Save it to ~/Documents/report.docxCreate 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.docxCreate 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.docxThe 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 infoMCP 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 MathComponent AST parser (used by insert_equation v3.2.0+)
markdown-swift (v0.2.0+) — Markdown generation
word-to-md-swift (v0.4.0+) — Word to Markdown conversion
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 RealWorldDocxRoundTripSmokeTestsPer-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.
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 |
Benchmarks on Apple Silicon (M4 Max, 128GB RAM):
File Size | Time |
40 KB (thesis outline) | 72 ms |
431 KB (complex document) | 31 ms |
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 |
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.
MIT License
Che Cheng (@PsychQuant)
@ildunari — session state management (v1.17.0)
che-apple-mail-mcp - Apple Mail MCP server
che-ical-mcp - macOS Calendar MCP server
This server cannot be deployed
Generate, edit, merge, translate and PDF-convert PowerPoint (.pptx) over MCP. 8 tools.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Use your own Word templates to convert Markdown → DOCX/PDF/HTML from any MCP-compatible AI.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.