MCP Docx

mcp-docx

用于Word文档的MCP（模型上下文协议）服务器：生成、编辑和操作 .docx 来自Cursor、Claude或任何MCP客户端的文件。用Python实现。

特性

• 生成 模板中的文档（Jinja2占位符 {{ name }}, {{ date }})或从头开始创建新文档； 邮件合并 对于Word合并字段(«Nome», «Data»)
• 编辑 现有文档：替换占位符，插入段落
• 操纵 文档：合并多个文件，提取纯文本，获取元数据（段落数、字数）
• 格式 具有标题、标题、项目符号列表和 图像 （可选额外）
• 转换 通过Pandoc将PDF转换为.docx、.docx转换为HTML以及其他格式（可选附加）

需求

• Python 3.10+
• pip或uv

安装

git clone https://github.com/AndersonTaborga/mcp-docx.git
cd mcp-docx
pip install -e .

或者使用紫外线：

uv pip install -e .

光标配置

在中添加MCP服务器 光标设置→ MCP 或者直接编辑配置文件：

• 窗户： %USERPROFILE%\.cursor\mcp.json
• macOS/Linux： ~/.cursor/mcp.json

示例（从项目根目录运行；使用您的实际项目路径 cwd):

{
  "mcpServers": {
    "mcp-docx": {
      "command": "python",
      "args": ["-m", "mcp_docx.server"],
      "cwd": "C:/path/to/mcp-docx-python"
    }
  }
}

你 必须 集 cwd 到项目根（其中 pyproject.toml 和 src/ 生活）所以 mcp_docx 可以加载模块。

或者，在 pip install -e .，您可以使用已安装的脚本（仍设置 cwd 如果需要，可以加入该项目）：

{
  "mcpServers": {
    "mcp-docx": {
      "command": "mcp-docx",
      "cwd": "C:/path/to/mcp-docx-python"
    }
  }
}

如果光标未找到 python 在PATH中，使用Python可执行文件的完整路径（例如。 C:/Users/You/AppData/Local/Programs/Python/Python310/python.exe 在Windows上）。

工具

所有工具都接受路径 .docx （或其他注明的格式）在服务器进程可访问的文件系统上。

可选功能

某些工具需要可选的依赖关系。使用以下方式安装它们：

pip install mcp-docx[pdf,html,images,mailmerge]
# or install everything including Pandoc support:
pip install mcp-docx[all]

如果没有相应的额外信息，该工具会返回一条错误消息，指示您安装它（例如。 pip install mcp-docx[pdf]).

示例：generate_from_template

• 模板路径：通往a的道路 .docx 模板，例如。 Hello {{ name }}, date: {{ date }}.
• outputPath：将生成的文件写入何处。
• 数据: { "name": "World", "date": "2025-01-01" }.

示例：create_document

• outputPath：输出文件的路径。
• 标题：文档标题。
• 段落：字符串数组，例如。 ["First paragraph.", "Second paragraph."].

示例：create_document_formated

• outputPath：输出文件的路径。
• 内容块：对象数组。每个对象都有 类型 以及：

- {"type": "heading", "level": 1 or 2, "text": "Section title"} - {"type": "paragraph", "text": "Body text."} - {"type": "list_bullet", "items": ["Item one.", "Item two."]} - {"type": "image", "path": "/path/to/image.png", "width_inches": 2.0} （要求 [images])

• 标题 （可选）：居中的文档标题。
• 字幕 （可选）：居中字幕。
• font_name （可选）：默认字体，例如。 "Calibri".
• font_size_pt （可选）：默认字体大小，例如。 11.

示例：mail_merge

• 模板路径：带有Word合并字段的.docx路径（例如。 «Nome», «Data»).
• outputPath：填写文件的位置。
• 合并数据: { "Nome": "João", "Data": "2025-01-15" }.退货 { "outputPath": "...", "message": "..." }.

示例：convert_pdf_to_docx

• pdf_path：PDF文件的路径。
• 输出路径：输出.docx的路径。退货 { "outputPath": "...", "message": "..." }.

示例：docx_to_html

• 文档路径：.docx文件的路径。退货 `{ "html": "

... ", "messages": [] }`.

示例：convert_document

• 输入路径：源文件的路径。
• 输出路径：输出文件的路径。
• 输出格式：例如。 "docx", "html", "md".退货 { "outputPath": "...", "message": "..." }.

示例：extract_text

• documentPath：通往 .docx 文件。退货 { "text": "..." }.

架构和工作流程

堆栈（架构）

flowchart TB
  Client[Cursor / IDE]
  MCP[mcp-docx Server]
  Gen[tools_generate]
  Edit[tools_edit]
  Manip[tools_manipulate]
  Conv[tools_convert]
  Lib[lib/docx_utils]
  Docx[python-docx]
  Docxtpl[docxtpl]
  Pdf[pdf2docx]
  Mammoth[mammoth]
  MailMerge[docx-mailmerge]
  Pandoc[pypandoc]
  Pillow[Pillow]
  Client --> MCP
  MCP --> Gen
  MCP --> Edit
  MCP --> Manip
  MCP --> Conv
  Gen --> Lib
  Gen --> Docxtpl
  Edit --> Docxtpl
  Manip --> Lib
  Conv --> Pdf
  Conv --> Mammoth
  Conv --> Pandoc
  Gen --> MailMerge
  Lib --> Docx
  Gen --> Pillow

工具类别

flowchart LR
  subgraph Generate
    create_document
    create_document_formatted
    generate_from_template
    mail_merge
  end
  subgraph Edit
    replace_text
    insert_paragraph
  end
  subgraph Manipulate
    merge_documents
    extract_text
    get_document_info
  end
  subgraph Convert
    convert_pdf_to_docx
    docx_to_html
    convert_document
  end

流程：生成vs转换

flowchart TD
  A[Need a document] --> B{How?}
  B -->|From scratch| C[create_document / create_document_formatted]
  B -->|Jinja2 template| D[generate_from_template]
  B -->|Word merge fields| E[mail_merge]
  B -->|PDF source| F[convert_pdf_to_docx]
  B -->|docx to web| G[docx_to_html]
  B -->|Other formats| H[convert_document - Pandoc]

兼容性

输出是标准的Office Open XML（OOXML），与Microsoft Word和其他支持 .docx。模板最好在Word中创建和格式化，以获得最佳保真度。

文本编码

所有文本输入都应 Unicode（UTF-8）。服务器在写入之前将文本标准化为Unicode NFC，以便正确存储葡萄牙语和其他重音字符。

代理技能

此存储库包括 代理技能 （SKILL.md）in .cursor/技能/ 以便Cursor的代理使用mcp-docx-mcp，具有更好的格式、生成和流畅性。当您在Cursor中打开此项目时，代理可以自动加载这些技能（从 .cursor/skills/ 或 .agents/skills/).

技能遵循 代理技能 格式。它们不会改变MCP服务器；他们指导代理何时以及如何调用工具。

贡献

看 贡献.md.开发已完成 dev 分支； main 用于生产发布。

测试MCP

在Cursor中安装和配置服务器后，您可以要求AI使用 创建_文档 工具（或任何其他工具）生成 .docx 在您选择的文件夹中。例子： *“通过MCP创建一个标题为X和两段的测试文档。”* AI将调用MCP，文件将写入您或AI指定的路径。

许可证

麻省理工学院