Skip to main content
Glama
deenesjakoruzh
PsychQuant

che-word-mcp

by PsychQuant
OverviewSchemaRelated ServersScoreDiscussions
Local

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-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)

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

(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

(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

(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

(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-plugins and /plugin install che-word-mcp@psychquant-claude-plugins work 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.version is 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_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/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_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".

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 (with as_revision flag). Run the server and call tools/list for 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 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

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

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
<1hResponse time
1dRelease cycle
82Releases (12mo)
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PsychQuant/che-word-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server