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 配置
- 复制配置到 Claude：
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
- 更新配置中的路径：
{
"mcpServers": {
"docx-mcp": {
"command": "uv",
"args": [
"--directory",
"/你的/docx-mcp/路径",
"run",
"python",
"-m",
"docx_mcp.server"
]
}
}
}
- 重启 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 文档管理能力。