DOCX文档处理服务

docx mcp服务器

本地人 主控程序 用于读取和编辑Word（.docx）文档的服务器。适用于Claude Code、Cursor和任何兼容MCP的客户端。

40工具 用于文档内容、格式、注释、页面布局和跟踪更改——所有这些都通过stdio在本地运行，无需上传文件。

特性

跟踪更改

编辑工具(replace_texts, edit_paragraphs, insert_paragraphs, delete_paragraphs)支持 跟踪的修改 --编辑被记录为Word修订(w:ins/w:del)带有作者和时间戳，因此审阅者可以在Word中接受或拒绝它们。

跟踪更改是 默认开启.通行证 track_changes: false 进行直接编辑。

使用 read_document 和 show_revisions: true 查看注释为的跟踪更改 [-deleted-] 和 [+inserted+]。默认视图仅显示接受的文本。

使用 accept_all_changes / reject_all_changes 最终确定或恢复所有待定的修订。

稳定锚

段落通常由整数块索引寻址，但每次插入/删除都会移动后面块的索引，因此每次更改后都必须重新读取多步编辑。 锚点 修复这个问题：锚点是一个稳定的id（Word的 w14:paraId)在整个索引变化过程中，它都会附着在段落上。

• 跑 ensure_anchors 一次为每个段落分配锚点并获取完整索引→锚点映射（大多数Word编写的文档已经带有锚点；调用是幂等的）。
• search_text 返回每场比赛的 anchor，以及 read_document 和 show_anchors: true 将它们内联打印。
• 编辑工具(edit_paragraphs, delete_paragraphs, set_paragraph_formats, set_headings, insert_paragraphs)接受a anchor （或 anchors)作为替代方案 paragraph_index.编辑还会自动为每个被触摸/插入的段落分配一个锚点 insert_paragraphs 返回新锚点，因此管道可以继续编辑而无需重新读取。

v1锚点覆盖顶级（正文）段落；表或内容控件中的段落未锚定。

页面布局

get_page_layout / set_page_layout 支持：

• 页面大小预设：A3、A4、A5、B4、B5、信纸、法律
• 预设边距：普通、窄、宽，JP Court 25mm，JP Court 30/20mm
• 自定义值 页面大小和单个边距以毫米为单位
• 定向 （肖像/风景）

快速开始

选项1：从npm安装

npm install -g @knorq/docx-mcp-server

然后添加到MCP配置中（请参阅 配置 在......下面

选项2：使用npx（不安装）

只需添加配置-- npx 自动下载并运行它：

{
  "mcpServers": {
    "docx-editor": {
      "command": "npx",
      "args": ["-y", "@knorq/docx-mcp-server"]
    }
  }
}

选项3：从源代码构建

git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm link        # makes `docx-mcp-server` available globally

配置

克劳德代码

添加到您的项目 .mcp.json （每个项目）或 ~/.claude/settings.json （全球）：

{
  "mcpServers": {
    "docx-editor": {
      "command": "npx",
      "args": ["-y", "@knorq/docx-mcp-server"]
    }
  }
}

光标

在游标设置中添加到MCP服务器配置：

{
  "mcpServers": {
    "docx-editor": {
      "command": "npx",
      "args": ["-y", "@knorq/docx-mcp-server"]
    }
  }
}

使用本地构建（不使用npm）

如果你从源代码构建并运行 npm link:

{
  "mcpServers": {
    "docx-editor": {
      "command": "docx-mcp-server"
    }
  }
}

或者直接引用构建的文件：

{
  "mcpServers": {
    "docx-editor": {
      "command": "node",
      "args": ["/absolute/path/to/docx-mcp-server/dist/index.js"]
    }
  }
}

分发给他人

通过npm（推荐）

npm publish

收件人安装时使用：

npm install -g @knorq/docx-mcp-server

或者完全跳过安装——只需分享 .mcp.json 配置为 npx 上面的设置，它开箱即用。

通过zip/git

共享存储库。收件人运行：

git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm link

然后添加上面的配置。

工具参考

阅读

read_document --使用块索引、样式和格式提示阅读内容。使用 show_revisions 查看跟踪的变化。

file_path, start_paragraph?, end_paragraph?, show_revisions?

get_document_info --段落计数、标题大纲、表格计数、评论状态。

file_path

search_text --使用上下文片段进行搜索。

file_path, query, case_sensitive?

list_images --列出所有嵌入的图像，包括文件名、尺寸、alt文本和块索引。

file_path

get_paragraph_format --反思段落的格式（样式、标题级别、对齐方式、编号、斜线缩进、点间距）。使用它来查找 copy_format_from 源代码或调试为什么两个段落呈现不同。值与单位匹配 set_paragraph_formats 接受。

file_path, paragraph_index

ensure_anchors --指定一个稳定的锚点(w14:paraId)对每个缺少一个的顶级段落返回索引→锚定地图。我暂时没有。看 稳定锚.

file_path

编辑

所有编辑工具均接受 track_changes （默认值 true)以及 author （默认值 "Claude").下面的段落工具接受 anchor （或 anchors)代替 paragraph_index 如需了解防索引偏移的目标定位，请参见 稳定锚.

replace_texts --在单个打开/保存周期中应用一个或多个查找/替换操作。处理跨越多个运行的文本。

• 在...之下 track_changes: false，项目按顺序应用：后面的项目可以匹配前面项目生成的文本。
• 在...之下 track_changes: true （默认），引擎拒绝重叠的项目，其中项目N search 与任何较早的项目M共享文本 replace （在任何方向上）。跟踪的顺序替换无法安全地链接重叠的项目——嵌套 w:ins/w:del 不往返通过 reject_all_changes.解决方法：单独发布 replace_texts 调用（每个项目一个）或使用 track_changes: false 和 allow_untracked_edit: true.

file_path, items (array of {search, replace, case_sensitive?}), track_changes?, author?, include_headers_footers?

edit_paragraphs --替换单个打开/保存周期中一个或多个段落的文本内容。每个目标 paragraph_index 或 anchorA. \n 在 new_text 是段落分隔：未跟踪的编辑将其拆分为单独的段落（每个段落继承原始编号/缩进），跟踪的编辑保留一个段落并呈现 \n 作为软线断裂。

file_path, edits (array of {paragraph_index? | anchor?, new_text}), track_changes?, author?

insert_paragraphs --在一个操作中插入一个或多个段落。按以下方式放置 position （块索引）或 anchor + placement （“之前”/“之后”）；返回新段落的锚点。A. \n 在 text 是段落分隔符（未跟踪：每行一段；跟踪：软换行）。当几个段落共享相同内容时 position，它们在文档中的位置与数组顺序相反——从后到前列出它们或使用单独的调用（锚点位置保留数组顺序）。

file_path, paragraphs (array of {text, position? | (anchor + placement), style?, num_id?, num_level?, copy_format_from?, copy_format_from_anchor?}), track_changes?, author?

delete_paragraphs --在一次操作中删除一个或多个段落或表格块。目标由 paragraph_indices （段落或表格）和/或 anchors （仅段落）。

file_path, paragraph_indices?, anchors?, track_changes?, author?

格式化

format_text --将粗体、斜体、下划线、字体、大小、颜色、突出显示应用于匹配的文本。

file_path, search, bold?, italic?, underline?, strikethrough?, highlight_color?, font_name?, font_size?, font_color?, case_sensitive?

set_paragraph_formats --在一次操作中对一个或多个段落应用对齐、间距、缩进。每组以段落为目标 indices 和 anchors 并捆绑格式以应用于它们。

file_path, groups (array of {indices?, anchors?, alignment?, space_before?, space_after?, line_spacing?, indent_left?, indent_right?, first_line_indent?, hanging_indent?})

highlight_text --用颜色突出显示匹配的文本。

file_path, search, color?, case_sensitive?

set_headings --在一次操作中将一个或多个段落转换为标题（级别1-9）。每个目标 paragraph_index 或 anchor.

file_path, headings (array of {paragraph_index? | anchor?, level})

结构

insert_table --插入一个包含可选单元格数据的表。

file_path, position, rows, cols, data?

create_document --创建一个新的.docx文件，其中预设了可选的标题、内容和样式。

file_path, title?, content?, preset?

默认情况下 create_document 使生成的文档保持通用。如果你想要一份日本商务文件作为起点，请通过 preset: "ja-business" 播种 styles.xml 采用余哥特式正文，尺寸为11pt，段落间距更大，标题间距更小。

apply_document_preset --通过更新一次性应用文档范围内的样式预设 styles.xml.

file_path, preset

当您想重新设置现有文档的样式而不重复时，请使用此选项 format_text 每段通话。预设值会重写 docDefaults 和那个 Heading 1–Heading 3 风格；现有 Normal 样式和其他自定义样式得以保留。

审查

add_comment --将评论锚定到特定文本。

file_path, anchor_text, comment_text, author?

add_comments --在一个操作中添加多个注释。支持部分成功。

file_path, comments (array of {anchor_text, comment_text, author?}), default_author?

read_comments --列出所有带有ID、作者、文本和线程回复的评论。

file_path

reply_to_comment --回复现有评论，创建线程对话。

file_path, parent_comment_id, comment_text, author?

delete_comment --按ID删除评论。

file_path, comment_id

跟踪更改

accept_all_changes --接受所有跟踪的更改。插入成为永久性的，删除被删除。

file_path

reject_all_changes --拒绝所有跟踪的更改。插入内容被删除，删除的文本被恢复。

file_path

页面布局

get_page_layout --阅读页面大小、边距、方向。

file_path

set_page_layout --通过预设或自定义的毫米值设置页面大小、边距和方向。

file_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?

页眉和页脚

read_header_footer --阅读所有页眉和页脚的文本内容。

file_path

表格

read_table_structure --在不阅读整个文档的情况下检查表格：行/列尺寸和每个单元格的简短预览，以及每个单元格的合并信息(gridSpan / vMerge).指数是物理的 w:tc 位置，匹配 read_table_cell / edit_table_cells.

file_path, block_index

read_table_cell --阅读单个单元格的段落（文本+样式/对齐/编号）并合并信息，而无需阅读整个文档。

file_path, block_index, row_index, col_index

edit_table_cells --在单个打开/保存周期中替换一个或多个表单元格的文本内容。单元格可以跨不同的表。A. \n 在 new_text 是段落分隔符：未跟踪的编辑将替换 全细胞将每一行都变成自己的段落（这样重新编辑就不会留下过时的行）；跟踪编辑diff替换单元格的第一段并呈现 \n 作为软线断裂。

file_path, edits (array of {block_index, row_index, col_index, new_text}), track_changes?, author?

edit_table_paragraphs --编辑单元格内的一个特定段落（单元格本地 paragraph_index)而无需更换整个电池。用于手术更改多段落单元格的单行（例如一个编号的列表项）。

file_path, edits (array of {block_index, row_index, col_index, paragraph_index, new_text}), track_changes?, author?

delete_table_paragraphs --删除单元格内的一个特定段落。如果删除的段落是单元格的最后一个段落，则保留空白段落（因此单元格保持有效）；真正的单词编号会自动对其余部分重新编号。

file_path, targets (array of {block_index, row_index, col_index, paragraph_index}), track_changes?, author?

insert_table_paragraphs --在单元格本地位置的单元格内插入段落(-1/超出范围附加）。支持 num_id/num_level 和 copy_format_from （同一单元格内的段落索引）。

file_path, inserts (array of {block_index, row_index, col_index, position, text, style?, num_id?, num_level?, copy_format_from?}), track_changes?, author?

脚注

read_footnotes --阅读所有带有ID和文本内容的脚注。

file_path

为什么使用MCP工具而不是原始Python？

AI代理可以通过原始Python（Python-DOCX）操纵DOCX，但MCP工具的令牌效率要高得多：

场景比较（输出令牌，从实际代码中测量）

节省的金额尤其巨大 跟踪的修改, 评论，以及 运行级别格式化 -python-docx没有用于跟踪更改或注释的内置API，并且文本格式需要复杂的运行拆分逻辑。代理必须生成原始OOXML操作代码（每次操作约300-575个输出令牌）。MCP工具通过简单的参数调用在内部处理此问题。

简单的读取和段落格式操作节省的成本较小（约63-76%），因为python docx具有干净的API。

输出令牌的成本比输入令牌高5倍，因此消除代码生成会产生巨大的成本影响。一次性模式开销（40个工具约2500个令牌）在3-5次操作中即可收回成本。

需求

• Node.js 20+

许可证

麻省理工学院