docx-mcp

# docx-mcp: Word 文档 MCP 服务器 > 基于 [rajesh-docx-mcp](https://lobehub.com/zh/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） ### 快速开始 ```bash # 1. 克隆或进入项目目录 cd docx-mcp # 2. 运行安装脚本 ./setup.sh # 3. 激活虚拟环境 source venv/bin/activate # 4. 运行服务器 ./run.sh ``` ### 手动安装 ```bash # 创建并激活虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 uv sync # 运行服务器 python -m docx_mcp.server ``` ## 配置使用 ### Claude Desktop 配置 1. 复制配置到 Claude： ```bash cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 2. 更新配置中的路径： ```json { "mcpServers": { "docx-mcp": { "command": "uv", "args": [ "--directory", "/你的/docx-mcp/路径", "run", "python", "-m", "docx_mcp.server" ] } } } ``` 3. 重启 Claude Desktop ### Kiro 配置 在 `.kiro/settings/mcp.json` 中添加： ```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]) ``` ## 环境变量配置 ```bash # 文档访问的项目目录 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 模板格式 ## 开发 ### 运行测试 ```bash # 安装开发依赖 uv sync --all-extras # 运行所有测试 uv run pytest tests/ # 带覆盖率运行 uv run pytest tests/ --cov=src/docx_mcp ``` ### 代码风格 ```bash # 格式化代码 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 目录下。 ### 虚拟环境问题 ```bash rm -rf venv/ ./setup.sh ``` ### 服务器无法启动 ```bash # 检查 Python 版本 python3 --version # 应为 3.10+ # 查看日志 cat logs/docx_mcp_*.log ``` ## 许可证 MIT --- 基于 FastMCP 和 python-docx 构建，提供全面的 Word 文档管理能力。