docx-mcp: Word 文档 MCP 服务器

基于 rajesh-docx-mcp 开发改进

一个功能全面的 Model Context Protocol (MCP) 服务器，用于读取、写入和操作 Microsoft Word (.docx) 文档。提供 30+ 工具，覆盖文档全生命周期管理，从基础文本操作到高级格式化、模板和内容控制。

功能特性

核心文档操作

• create_docx - 创建新的空白文档
• read_docx - 提取文本和元数据
• write_docx - 写入/覆盖文档内容
• append_docx - 追加内容到现有文档
• list_docx - 列出目录中的文档
• delete_docx - 安全删除文档
• copy_docx - 复制文档到新位置

Word 原生模板系统

• list_merge_fields - 提取文档中的 MERGEFIELD 名称
• fill_merge_fields - 用数据替换合并字段值
• list_content_controls - 列出所有内容控件
• get_document_properties - 读取文档元数据
• set_document_properties - 更新文档元数据

样式管理

• list_styles - 列出所有可用的段落和字符样式
• apply_paragraph_style - 应用命名样式（"标题 1"、"正文"等）

列表 - 项目符号和编号

• apply_bullet_list - 应用项目符号格式
• apply_numbered_list - 应用编号格式
• set_list_level - 控制列表缩进级别（0-8）

图片和标题

• insert_image - 插入图片并设置尺寸
• add_image_caption - 添加自动编号的标题
• list_images - 列出文档中的所有图片
• extract_images - 提取图片并保存或返回 base64 编码

公式提取（新增）

• list_equations - 列出文档中所有数学公式，转换为 LaTeX 格式
• get_equation - 获取指定索引的公式详情

其他特性

• 结构化 JSON 日志
• 安全优先设计，带路径验证
• 全面的错误处理
• 支持文档属性和元数据
• MCP 资源端点用于文档内容访问

安装

前置要求

• Python 3.10 或更高版本
• uv 包管理器（或 pip）

快速开始

# 1. 克隆或进入项目目录
cd docx-mcp

# 2. 运行安装脚本
./setup.sh

# 3. 激活虚拟环境
source venv/bin/activate

# 4. 运行服务器
./run.sh

手动安装

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
uv sync

# 运行服务器
python -m docx_mcp.server

配置使用

Claude Desktop 配置

1. 复制配置到 Claude：

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 更新配置中的路径：

{
  "mcpServers": {
    "docx-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/你的/docx-mcp/路径",
        "run",
        "python",
        "-m",
        "docx_mcp.server"
      ]
    }
  }
}

3. 重启 Claude Desktop

Kiro 配置

在 .kiro/settings/mcp.json 中添加：

{
  "mcpServers": {
    "docx-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/你的/docx-mcp/路径",
        "run",
        "python",
        "-m",
        "docx_mcp.server"
      ]
    }
  }
}

使用示例

创建和写入文档

用户: 在 ./report.docx 创建一个新文档，标题为"月度报告"
工具: create_docx(filepath="./report.docx", title="月度报告")

用户: 写入一些内容
工具: write_docx(filepath="./report.docx", content="执行摘要\n主要发现...")

提取图片

用户: 提取文档中的所有图片
工具: extract_images(filepath="./doc.docx", output_dir="./images")

用户: 获取图片的 base64 编码
工具: extract_images(filepath="./doc.docx", return_base64=True)

提取公式

用户: 列出文档中的所有公式
工具: list_equations(filepath="./论文.docx")

用户: 获取第 18 个公式
工具: get_equation(filepath="./论文.docx", equation_index=17)

应用样式和格式

用户: 列出文档中可用的样式
工具: list_styles(filepath="./report.docx")

用户: 将第一段应用"标题 1"样式
工具: apply_paragraph_style(filepath="./report.docx", paragraph_index=0, style_name="Heading 1")

创建列表

用户: 将第 3-5 段设为项目符号列表
工具: apply_bullet_list(filepath="./report.docx", paragraph_indices=[3,4,5])

用户: 改为编号列表
工具: apply_numbered_list(filepath="./report.docx", paragraph_indices=[3,4,5])

环境变量配置

# 文档访问的项目目录
export DOCX_MCP_PROJECT_DIR=/path/to/documents

# 最大文件大小（默认：50MB）
export DOCX_MCP_MAX_FILE_SIZE=52428800

# 日志级别（DEBUG, INFO, WARNING, ERROR）
export DOCX_MCP_LOG_LEVEL=INFO

# 允许访问任意路径（谨慎使用）
export DOCX_MCP_ALLOW_UNSAFE_PATHS=true

文件系统安全

服务器验证所有文件路径以防止目录遍历攻击：

• 默认允许访问 home 目录下的所有路径
• 验证文件扩展名（.docx, .doc, .dotx, .dot）
• 强制文件大小限制
• 防止空字节注入

支持的文档格式

• .docx - 现代 Microsoft Word 格式（推荐）
• .doc - 旧版 Microsoft Word 格式
• .dotx - Word 模板格式
• .dot - 旧版 Word 模板格式

开发

运行测试

# 安装开发依赖
uv sync --all-extras

# 运行所有测试
uv run pytest tests/

# 带覆盖率运行
uv run pytest tests/ --cov=src/docx_mcp

代码风格

# 格式化代码
uv run black src/ tests/

# 检查代码
uv run ruff check src/ tests/

# 类型检查
uv run mypy src/

项目结构

docx-mcp/
├── src/docx_mcp/
│   ├── __init__.py           # 包初始化
│   ├── server.py             # 主 MCP 服务器及所有工具
│   ├── config.py             # 配置管理
│   ├── logging_config.py     # 日志设置
│   ├── exceptions.py         # 自定义异常类
│   └── utils/
│       ├── path_utils.py     # 路径验证和规范化
│       ├── document_utils.py # 文档处理工具
│       └── __init__.py
├── tests/                    # 测试文件
├── pyproject.toml            # 项目元数据和依赖
├── setup.sh                  # 环境安装脚本
├── run.sh                    # 服务器启动脚本
└── README.md                 # 本文件

故障排除

在其他项目路径无法使用

设置环境变量 DOCX_MCP_ALLOW_UNSAFE_PATHS=true 或确保文档在 home 目录下。

虚拟环境问题

rm -rf venv/
./setup.sh

服务器无法启动

# 检查 Python 版本
python3 --version  # 应为 3.10+

# 查看日志
cat logs/docx_mcp_*.log

许可证

MIT

---

基于 FastMCP 和 python-docx 构建，提供全面的 Word 文档管理能力。