{"_id":"@knorq/docx-mcp-server","_rev":"3-e8aab6848931ac14969e68c609bc3e1c","name":"@knorq/docx-mcp-server","dist-tags":{"latest":"3.1.0"},"versions":{"2.0.0":{"name":"@knorq/docx-mcp-server","version":"2.0.0","keywords":["mcp","docx","word","document","editor","track-changes","model-context-protocol"],"author":{"name":"docx-mcp-server contributors"},"license":"MIT","_id":"@knorq/docx-mcp-server@2.0.0","maintainers":[{"name":"knorq","email":"info@knorq.com"}],"homepage":"https://github.com/knorq-ai/docx-mcp-server#readme","bugs":{"url":"https://github.com/knorq-ai/docx-mcp-server/issues"},"bin":{"docx-mcp-server":"dist/index.js"},"dist":{"shasum":"199845fe67c3e9524f4d16e6bf4b3a016ab83272","tarball":"https://registry.npmjs.org/@knorq/docx-mcp-server/-/docx-mcp-server-2.0.0.tgz","fileCount":44,"integrity":"sha512-k5P46b85IztWbDwvnPKlqRXu6UDKgXp0m/soOD5ivD/SnMRQh9ZGpWm7jNpq0OXLy/tPdE+cjKksLo+Qa3b8dg==","signatures":[{"sig":"MEUCIFfUR8eGrlSQpjFNsb1hCv7dHZDB+cgZrscyxYGYCAh/AiEA4bWWb+lrbMphWj3uVhNJu6sLZNNuMMoO7KBDjfuF5ro=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":453249},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"303d005c1f6eb6bf1e0cd07009dbd62de9933824","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"knorq","email":"info@knorq.com"},"repository":{"url":"git+https://github.com/knorq-ai/docx-mcp-server.git","type":"git"},"_npmVersion":"11.5.1","description":"MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents","directories":{},"_nodeVersion":"24.5.0","dependencies":{"zod":"^3.24.0","jszip":"^3.10.1","fast-xml-parser":"^5.3.3","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^4.0.18","typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/docx-mcp-server_2.0.0_1776392147843_0.3307745020859214","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@knorq/docx-mcp-server","version":"2.1.0","keywords":["mcp","docx","word","document","editor","track-changes","model-context-protocol"],"author":{"name":"docx-mcp-server contributors"},"license":"MIT","_id":"@knorq/docx-mcp-server@2.1.0","maintainers":[{"name":"knorq","email":"info@knorq.com"}],"homepage":"https://github.com/knorq-ai/docx-mcp-server#readme","bugs":{"url":"https://github.com/knorq-ai/docx-mcp-server/issues"},"bin":{"docx-mcp-server":"dist/index.js"},"dist":{"shasum":"63a73070bcd1aa8bdfceb67ea1ab3586c8310ff2","tarball":"https://registry.npmjs.org/@knorq/docx-mcp-server/-/docx-mcp-server-2.1.0.tgz","fileCount":44,"integrity":"sha512-PqVWcsi3R+d2XIrp//Jl0B/vEEX6za5qoh64N1iMPIz84Jkbcse3765R5PNtUvz4X2VOM+VxM6YJRoJSOQ4Isg==","signatures":[{"sig":"MEYCIQDuZtN1TkknaVUYTtnxspJ+8cH3I7F8mbz85DFzxVFcYAIhALXHWpqCoWFOdrINohUXfpfTLoRn2yhXhO6+rk+VjyEy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":466072},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"b74b2308ad2db53cf9165022a9086ef2788d5088","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"knorq","email":"info@knorq.com"},"repository":{"url":"git+https://github.com/knorq-ai/docx-mcp-server.git","type":"git"},"_npmVersion":"11.5.1","description":"MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents","directories":{},"_nodeVersion":"24.5.0","dependencies":{"zod":"^3.24.0","jszip":"^3.10.1","fast-xml-parser":"^5.3.3","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^4.0.18","typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/docx-mcp-server_2.1.0_1777008421407_0.8286366049837823","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@knorq/docx-mcp-server","version":"3.1.0","description":"MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents","type":"module","main":"dist/index.js","bin":{"docx-mcp-server":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["mcp","docx","word","document","editor","track-changes","model-context-protocol"],"author":{"name":"docx-mcp-server contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/knorq-ai/docx-mcp-server.git"},"homepage":"https://github.com/knorq-ai/docx-mcp-server#readme","bugs":{"url":"https://github.com/knorq-ai/docx-mcp-server/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","fast-xml-parser":"^5.3.3","jszip":"^3.10.1","zod":"^3.24.0"},"devDependencies":{"@types/node":"^20.0.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^4.0.18"},"_id":"@knorq/docx-mcp-server@3.1.0","gitHead":"2889d56cce990abee2cc165081495377ef1e20a7","types":"./dist/index.d.ts","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-00r98ugE7EcEFex+XmXe3JBHdVBp9MaTplIxhk4dGF1GreJLXLALDZKGtkkzQhMACdvfkfqeCvOOvKaN+ZCvMw==","shasum":"be456b76232ee4da973712e3870c7b98d0806047","tarball":"https://registry.npmjs.org/@knorq/docx-mcp-server/-/docx-mcp-server-3.1.0.tgz","fileCount":44,"unpackedSize":450787,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@knorq%2fdocx-mcp-server@3.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCsfddL8oTrsAYb6Z9VoD4P2CtY6lJ5r/Bi4BQOvtwnVgIhAOJhCM2BYHvAPo5OY0BjjM8wagW6nv4rZ/mDzMVHcinP"}]},"_npmUser":{"name":"knorq","email":"info@knorq.com"},"directories":{},"maintainers":[{"name":"knorq","email":"info@knorq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/docx-mcp-server_3.1.0_1777781559181_0.7798772958097471"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-17T02:15:47.723Z","modified":"2026-05-03T04:12:39.623Z","2.0.0":"2026-04-17T02:15:48.153Z","2.1.0":"2026-04-24T05:27:01.544Z","3.1.0":"2026-05-03T04:12:39.341Z"},"bugs":{"url":"https://github.com/knorq-ai/docx-mcp-server/issues"},"author":{"name":"docx-mcp-server contributors"},"license":"MIT","homepage":"https://github.com/knorq-ai/docx-mcp-server#readme","keywords":["mcp","docx","word","document","editor","track-changes","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/knorq-ai/docx-mcp-server.git"},"description":"MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents","maintainers":[{"name":"knorq","email":"info@knorq.com"}],"readme":"# docx-mcp-server\n\n[![CI](https://github.com/knorq-ai/docx-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/knorq-ai/docx-mcp-server/actions/workflows/ci.yml)\n\nA local [MCP](https://modelcontextprotocol.io/) server for reading and editing Word (.docx) documents. Works with Claude Code, Cursor, and any MCP-compatible client.\n\n**33 tools** for document content, formatting, comments, page layout, and track changes — all running locally via stdio with no file uploads.\n\n## Features\n\n| Category | Tools |\n|---|---|\n| **Read** | `read_document`, `get_document_info`, `search_text`, `list_images` |\n| **Edit** | `replace_texts`, `edit_paragraphs`, `insert_paragraphs`, `delete_paragraphs` |\n| **Format** | `format_text`, `set_paragraph_formats`, `highlight_text`, `set_headings` |\n| **Structure** | `insert_table`, `create_document`, `apply_document_preset` |\n| **Review** | `add_comment`, `add_comments`, `read_comments`, `reply_to_comment`, `delete_comment` |\n| **Track changes** | `accept_all_changes`, `reject_all_changes` |\n| **Page layout** | `get_page_layout`, `set_page_layout` |\n| **Headers/footers** | `read_header_footer` |\n| **Tables** | `edit_table_cells` |\n| **Footnotes** | `read_footnotes` |\n\n### Track changes\n\nThe editing tools (`replace_texts`, `edit_paragraphs`, `insert_paragraphs`, `delete_paragraphs`) support **tracked changes** — edits are recorded as Word revisions (`w:ins`/`w:del`) with author and timestamp, so reviewers can accept or reject them in Word.\n\nTrack changes is **on by default**. Pass `track_changes: false` to make direct edits.\n\nUse `read_document` with `show_revisions: true` to see tracked changes annotated as `[-deleted-]` and `[+inserted+]`. The default view shows accepted text only.\n\nUse `accept_all_changes` / `reject_all_changes` to finalize or revert all pending revisions.\n\n### Page layout\n\n`get_page_layout` / `set_page_layout` support:\n\n- **Page size presets**: A3, A4, A5, B4, B5, Letter, Legal\n- **Margin presets**: Normal, Narrow, Wide, JP Court 25mm, JP Court 30/20mm\n- **Custom values** in millimeters for page size and individual margins\n- **Orientation** (portrait / landscape)\n\n## Quick start\n\n### Option 1: Install from npm\n\n```bash\nnpm install -g @knorq/docx-mcp-server\n```\n\nThen add to your MCP config (see [Configuration](#configuration) below).\n\n### Option 2: Use npx (no install)\n\nJust add the config — `npx` downloads and runs it automatically:\n\n```json\n{\n  \"mcpServers\": {\n    \"docx-editor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@knorq/docx-mcp-server\"]\n    }\n  }\n}\n```\n\n### Option 3: Build from source\n\n```bash\ngit clone https://github.com/knorq-ai/docx-mcp-server.git\ncd docx-mcp-server\nnpm install\nnpm run build\nnpm link        # makes `docx-mcp-server` available globally\n```\n\n## Configuration\n\n### Claude Code\n\nAdd to your project's `.mcp.json` (per-project) or `~/.claude/settings.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"docx-editor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@knorq/docx-mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your MCP server configuration in Cursor settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"docx-editor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@knorq/docx-mcp-server\"]\n    }\n  }\n}\n```\n\n### Using a local build (without npm)\n\nIf you built from source and ran `npm link`:\n\n```json\n{\n  \"mcpServers\": {\n    \"docx-editor\": {\n      \"command\": \"docx-mcp-server\"\n    }\n  }\n}\n```\n\nOr reference the built file directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"docx-editor\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/docx-mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Distributing to others\n\n### Via npm (recommended)\n\n```bash\nnpm publish\n```\n\nRecipients install with:\n\n```bash\nnpm install -g @knorq/docx-mcp-server\n```\n\nOr skip the install entirely — just share the `.mcp.json` config with the `npx` setup above and it works out of the box.\n\n### Via zip / git\n\nShare the repository. Recipients run:\n\n```bash\ngit clone https://github.com/knorq-ai/docx-mcp-server.git\ncd docx-mcp-server\nnpm install\nnpm run build\nnpm link\n```\n\nThen add the config above.\n\n## Tool reference\n\n### Reading\n\n**`read_document`** — Read content with block indices, styles, and formatting hints. Use `show_revisions` to see tracked changes.\n```\nfile_path, start_paragraph?, end_paragraph?, show_revisions?\n```\n\n**`get_document_info`** — Paragraph count, heading outline, table count, comment status.\n```\nfile_path\n```\n\n**`search_text`** — Search with context snippets.\n```\nfile_path, query, case_sensitive?\n```\n\n**`list_images`** — List all embedded images with filenames, dimensions, alt text, and block indices.\n```\nfile_path\n```\n\n### Editing\n\nAll editing tools accept `track_changes` (default `true`) and `author` (default `\"Claude\"`).\n\n**`replace_texts`** — Apply one or more find/replace operations in a single open/save cycle. Handles text spanning multiple runs.\n- Under `track_changes: false`, items are applied sequentially: a later item can match text produced by an earlier item.\n- Under `track_changes: true` (default), the engine rejects overlapping items where item N's `search` shares text with any earlier item M's `replace` (in either direction). Tracked sequential replacement cannot safely chain overlapping items — nested `w:ins`/`w:del` does not round-trip through `reject_all_changes`. Workaround: issue separate `replace_texts` calls (one per item) or use `track_changes: false` with `allow_untracked_edit: true`.\n```\nfile_path, items (array of {search, replace, case_sensitive?}), track_changes?, author?, include_headers_footers?\n```\n\n**`edit_paragraphs`** — Replace the text content of one or more paragraphs in a single open/save cycle.\n```\nfile_path, edits (array of {paragraph_index, new_text}), track_changes?, author?\n```\n\n**`insert_paragraphs`** — Insert one or more paragraphs in one operation. Handles index shifting internally.\n```\nfile_path, paragraphs (array of {text, position, style?, num_id?, num_level?, copy_format_from?}), track_changes?, author?\n```\n\n**`delete_paragraphs`** — Delete one or more paragraphs in one operation. Handles index reordering internally.\n```\nfile_path, paragraph_indices, track_changes?, author?\n```\n\n### Formatting\n\n**`format_text`** — Apply bold, italic, underline, font, size, color, highlight to matching text.\n```\nfile_path, search, bold?, italic?, underline?, strikethrough?, highlight_color?, font_name?, font_size?, font_color?, case_sensitive?\n```\n\n**`set_paragraph_formats`** — Apply alignment, spacing, indentation to one or more paragraphs in one operation. Each group bundles a list of paragraph indices with the formatting to apply to them.\n```\nfile_path, groups (array of {indices, alignment?, space_before?, space_after?, line_spacing?, indent_left?, indent_right?, first_line_indent?, hanging_indent?})\n```\n\n**`highlight_text`** — Highlight matching text with a color.\n```\nfile_path, search, color?, case_sensitive?\n```\n\n**`set_headings`** — Convert one or more paragraphs to headings (level 1-9) in one operation.\n```\nfile_path, headings (array of {paragraph_index, level})\n```\n\n### Structure\n\n**`insert_table`** — Insert a table with optional cell data.\n```\nfile_path, position, rows, cols, data?\n```\n\n**`create_document`** — Create a new .docx file with optional title, content, and style preset.\n```\nfile_path, title?, content?, preset?\n```\n\nBy default `create_document` keeps the generated document generic. If you want a Japanese business-document starting point, pass `preset: \"ja-business\"` to seed `styles.xml` with Yu Gothic body text, 11pt sizing, roomier paragraph spacing, and less cramped heading spacing.\n\n**`apply_document_preset`** — Apply a document-wide style preset in one pass by updating `styles.xml`.\n```\nfile_path, preset\n```\n\nUse this when you want to restyle an existing document without repeated `format_text` calls per paragraph. The preset rewrites `docDefaults` and the `Heading 1`–`Heading 3` styles; an existing `Normal` style and other custom styles are preserved.\n\n### Review\n\n**`add_comment`** — Anchor a comment to specific text.\n```\nfile_path, anchor_text, comment_text, author?\n```\n\n**`add_comments`** — Add multiple comments in one operation. Supports partial success.\n```\nfile_path, comments (array of {anchor_text, comment_text, author?}), default_author?\n```\n\n**`read_comments`** — List all comments with IDs, authors, text, and threaded replies.\n```\nfile_path\n```\n\n**`reply_to_comment`** — Reply to an existing comment, creating a threaded conversation.\n```\nfile_path, parent_comment_id, comment_text, author?\n```\n\n**`delete_comment`** — Remove a comment by ID.\n```\nfile_path, comment_id\n```\n\n### Track changes\n\n**`accept_all_changes`** — Accept all tracked changes. Insertions become permanent, deletions are removed.\n```\nfile_path\n```\n\n**`reject_all_changes`** — Reject all tracked changes. Insertions are removed, deleted text is restored.\n```\nfile_path\n```\n\n### Page layout\n\n**`get_page_layout`** — Read page size, margins, orientation.\n```\nfile_path\n```\n\n**`set_page_layout`** — Set page size, margins, orientation by preset or custom mm values.\n```\nfile_path, page_size_preset?, orientation?, width_mm?, height_mm?, margin_preset?, top_mm?, right_mm?, bottom_mm?, left_mm?, header_mm?, footer_mm?, gutter_mm?\n```\n\n### Headers and footers\n\n**`read_header_footer`** — Read the text content of all headers and footers.\n```\nfile_path\n```\n\n### Tables\n\n**`edit_table_cells`** — Replace the text content of one or more table cells in a single open/save cycle. Cells can span different tables.\n```\nfile_path, edits (array of {block_index, row_index, col_index, new_text}), track_changes?, author?\n```\n\n### Footnotes\n\n**`read_footnotes`** — Read all footnotes with their IDs and text content.\n```\nfile_path\n```\n\n## Why MCP tools instead of raw Python?\n\nAI agents can manipulate DOCX via raw Python (python-docx), but MCP tools are significantly more token-efficient:\n\n| Metric | MCP tools | Raw Python |\n|--------|-----------|------------|\n| Output tokens per operation | **65–95% less** | Baseline (agent must generate full code) |\n| Cost per operation | **55–90% less** | Baseline |\n| Break-even | **3–5 operations** | — |\n| Debug iterations | None (validated inputs) | ~1.5 retries/task on average |\n\n### Scenario comparison (output tokens, measured from actual code)\n\n| Task | MCP | Python (python-docx) | Savings |\n|------|-----|---------------------|---------|\n| Read paragraphs 0–20 | ~18 | ~52 (open, iterate, print) | **65%** |\n| Search and replace text | ~16 | ~67 (iterate paragraphs, run traversal) | **76%** |\n| Add tracked change (insert) | ~32 | ~326 (build w:ins/w:del XML, datetime, author, run properties) | **90%** |\n| Add comment anchored to text | ~26 | ~575 (comment part, anchor markers, relationship, XML manipulation) | **95%** |\n| Format text (bold + color) | ~20 | ~478 (find runs, split at boundaries, apply rPr) | **96%** |\n| Set paragraph format (3 paragraphs) | ~30 | ~80 (load, resolve indices, set properties, save) | **63%** |\n| Composite: read → search → edit → comment | ~120 | ~1,000 | **88%** |\n\nThe savings are especially large for **tracked changes**, **comments**, and **run-level formatting** — python-docx has no built-in API for track changes or comments, and text formatting requires complex run-splitting logic. The agent must generate raw OOXML manipulation code (~300–575 output tokens per operation). MCP tools handle this internally with a simple parameter call.\n\nSimple read and paragraph-format operations see smaller savings (~63–76%) since python-docx has clean APIs for these.\n\nOutput tokens cost 5× more than input tokens, so eliminating code generation has an outsized cost impact. The one-time schema overhead (~2,500 tokens for 33 tools) pays for itself in 3–5 operations.\n\n## Requirements\n\n- Node.js 20+\n\n## License\n\nMIT\n","readmeFilename":"README.md"}