DOCX MCP Server

Universal DOCX processing server implementing the Model Context Protocol (MCP) with full OOXML support.

Features

• Full OOXML Support: Read/write all DOCX document parts (document.xml, styles, numbering, headers/footers, etc.)
• Text Operations: Extract, find, and replace text with literal or regex modes
• Table Editing: Insert/delete rows and columns, merge cells, set cell content
• Structured Data Tags (SDT): Get/set content controls by tag or alias
• Images: List images, insert inline or anchored images with position/size control
• Comments & Changes: List comments, add/delete comments, accept all tracked changes
• Document Properties: Read/write metadata (title, author, subject, etc.)
• LRU Caching: Memory-efficient caching of document parts
• Stdio Transport: MCP communication via stdin/stdout

Installation

npm install
npm run build

Running

Development

npm run dev

Production

npm start

With Claude Code

claude mcp add --scope user --transport stdio docx -- node /path/to/dist/index.js

Tools

Document Management

docx.open

Open a DOCX document from file or base64

{
  "docId": "uuid",
  "parts": ["word/document.xml", "word/styles.xml", ...],
  "partCount": 42,
  "props": { "core": {...}, "app": {...} }
}

docx.close

Close and unload a document

docx.save

Save document to file or return as base64

Part Management

docx.list_parts

List all parts in the document

docx.part_read

Read raw XML of a specific part

docx.part_write

Write/update XML content of a part

Text Operations

docx.get_text

Extract all text from document

{
  "docId": "uuid",
  "scope": "document" | "headers" | "footers" | "all"
}

docx.find

Search for text with context

{
  "docId": "uuid",
  "query": "search term",
  "mode": "literal" | "regex"
}

docx.replace_text

Replace text in document

{
  "docId": "uuid",
  "match": "old text",
  "replace": "new text",
  "mode": "literal" | "regex"
}

Tables

docx.tables_list

List all tables with dimensions

{
  "tables": [
    {
      "xpath": "/w:document/w:body/w:tbl[1]",
      "rows": 3,
      "colsApprox": 4
    }
  ]
}

docx.table_edit

Modify table structure and content

{
  "docId": "uuid",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": {
    "kind": "setCellText",
    "row": 0,
    "col": 1,
    "text": "new value"
  }
}

Operations:

• setCellText(row, col, text) - Set cell content
• insertRow(at) - Insert row at position
• deleteRow(at) - Delete row
• insertCol(at) - Insert column
• deleteCol(at) - Delete column

Structured Data (SDT)

docx.sdt_get

Get content control content by tag or alias

docx.sdt_put

Update content control

Images

docx.images_list

List all images with metadata

docx.image_add

Insert image inline or anchored

Styles & Numbering

docx.styles_get / docx.styles_set

Read/write styles.xml

docx.numbering_get / docx.numbering_set

Read/write numbering.xml

Headers/Footers

docx.headers_footers_list

List all header/footer parts

Comments

docx.comments_list

List all comments

docx.comments_add

Add new comment

docx.changes_accept_all

Accept all tracked changes in document

Metadata

docx.metadata_get

Get document properties (title, author, created, modified, etc.)

Test Scenarios

1. Basic Read/Write

# Open document
docx.open: { "path": "/path/to/document.docx" }

# Get text
docx.get_text: { "docId": "returned-id" }

# Replace text
docx.replace_text: {
  "docId": "returned-id",
  "match": "old text",
  "replace": "new text"
}

# Save
docx.save: { "docId": "returned-id", "returnBase64": true }

2. Table Manipulation

# List tables
docx.tables_list: { "docId": "id" }

# Edit cell
docx.table_edit: {
  "docId": "id",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": { "kind": "setCellText", "row": 0, "col": 0, "text": "Hello" }
}

3. Images

# List images
docx.images_list: { "docId": "id" }

4. Track Changes

# Accept all changes
docx.changes_accept_all: { "docId": "id" }

Architecture

src/
  index.ts                    # Entry point
  errors.ts                   # Error definitions
  logger.ts                   # Logging utilities
  ooxml/
    namespaces.ts            # XML namespace definitions
    emu.ts                    # EMU conversion utilities
    dom.ts                    # XML DOM utilities (xmldom + fontoxpath)
    xmlParser.ts              # fast-xml-parser wrapper
    parts.ts                  # DOCX ZIP part management
    rels.ts                   # Relationships management
    text.ts                   # Text extraction & replacement
    tables.ts                 # Table operations
    sdt.ts                    # Structured Data Tags
    drawings.ts               # Images & DrawingML
    headersFooters.ts         # Headers/Footers
    styles.ts                 # Style operations
    numbering.ts              # Numbering operations
    changes.ts                # Track changes
    comments.ts               # Comments
  store/
    types.ts                  # Type definitions
    docStore.ts               # Document store + LRU cache
  mcp/
    schemas.ts                # Tool input schemas
    tools.ts                  # Tool implementations
    server.ts                 # MCP server setup

Dependencies

• @modelcontextprotocol/sdk - MCP implementation
• jszip - ZIP archive handling
• fast-xml-parser - Lossless XML parsing
• @xmldom/xmldom - DOM implementation
• fontoxpath - XPath queries
• diff-match-patch - Text diffing
• lru-cache - Memory-efficient caching
• uuid - Document ID generation

Performance Notes

• Documents up to 10 MB supported
• LRU cache with 100-part limit and 1 GB memory cap
• Parts loaded on-demand, not fully into memory
• Dirty-part optimization: only modified parts saved to ZIP
• No deep copying of XML structures

Limitations

• Headers/footers: basic support (complex section structures may need manual adjustment)
• Comments: basic list/add/delete (reply chains not fully supported)
• Track changes: accept-all available; detailed change inspection limited
• Styles: get/set full XML; no selective style merging
• EMU/sizing: calculated but rendered geometry depends on Word's layout engine

License

MIT