使用说明

docx mcp：Word文档mcp服务器

一个全面的模型上下文协议（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 -列出所有可用的段落和字符样式
应用_段落_样式 -应用命名样式（“标题1”、“普通”等）

第4阶段：列表-项目符号和编号

应用程序_列表 -应用项目符号格式
应用程序编号列表 -应用编号格式
set_list_level -控制列表缩进级别（0-8）

第5阶段：图像和字幕

insert_image -插入带有尺寸选项的图像
add_image_caption -添加自动编号的字幕
list_images -列出文档中的所有图像

附加功能

结构化JSON日志记录
具有路径验证的安全第一设计
全面的错误处理
支持文档属性和元数据
用于文档内容访问的MCP资源端点

安装

先决条件

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

快速开始

# 1. Clone or navigate to the project
cd docx-mcp

# 2. Run setup script
./setup.sh

# 3. Activate virtual environment
source venv/bin/activate

# 4. Run the server
./run.sh

手动设置

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
uv sync

# Run server
python -m docx_mcp.server

与Claude一起使用

选项1：克劳德桌面

将配置复制到Claude：

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

更新docx mcp安装路径：

{
  "mcpServers": {
    "docx-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/docx-mcp",
        "run",
        "python",
        "-m",
        "docx_mcp.server"
      ]
    }
  }
}

重新启动克劳德桌面

选项2：程序化使用

from docx_mcp.server import app

# Access tools programmatically
# Or run via MCP protocol
app.run(transport="stdio")

示例命令

创建和编写文档

User: Create a new Word document at ./report.docx with the title "Monthly Report"
Tool: create_docx(filepath="./report.docx", title="Monthly Report")

User: Write some content to the document
Tool: write_docx(filepath="./report.docx", content="Executive Summary\nKey Findings...")

应用样式和格式

User: List available styles in the document
Tool: list_styles(filepath="./report.docx")

User: Apply Heading 1 style to the first paragraph
Tool: apply_paragraph_style(filepath="./report.docx", paragraph_index=0, style_name="Heading 1")

创建列表

User: Make paragraphs 3-5 a bulleted list
Tool: apply_bullet_list(filepath="./report.docx", paragraph_indices=[3,4,5])

User: Convert those to a numbered list instead
Tool: apply_numbered_list(filepath="./report.docx", paragraph_indices=[3,4,5])

User: Increase indentation to level 2
Tool: set_list_level(filepath="./report.docx", paragraph_index=3, level=2)

处理图像

User: Insert this image into the document
Tool: insert_image(filepath="./report.docx", image_path="./logo.png", width=2.5)

User: Add a caption to it
Tool: add_image_caption(filepath="./report.docx", image_index=0, caption_text="Company Logo", caption_type="Figure")

文档属性

User: Set document metadata
Tool: set_document_properties(
    filepath="./report.docx",
    author="John Doe",
    subject="Monthly Report",
    keywords="report,monthly,2024"
)

User: Get document properties
Tool: get_document_properties(filepath="./report.docx")

配置

环境变量

# Project directory for document access
export DOCX_MCP_PROJECT_DIR=/path/to/documents

# Maximum file size (default: 50MB)
export DOCX_MCP_MAX_FILE_SIZE=52428800

# Logging level (DEBUG, INFO, WARNING, ERROR)
export DOCX_MCP_LOG_LEVEL=INFO

文件系统安全

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

限制对已配置目录的访问
验证文件扩展名（.docx、.doc、.dotx、.dot）
强制文件大小限制
防止空字节注入

日志记录

日志存储在 logs/ 同时具有控制台和文件输出的目录：

控制台：人类可读格式
文件：用于日志聚合的JSON格式

发展

运行测试

# Install dev dependencies
uv sync --all-extras

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=src/docx_mcp

代码的风格

# Format code
uv run black src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

项目结构

docx-mcp/
├── src/docx_mcp/
│   ├── __init__.py           # Package initialization
│   ├── server.py             # Main MCP server with all tools
│   ├── config.py             # Configuration management
│   ├── logging_config.py     # Logging setup
│   ├── exceptions.py         # Custom exception classes
│   ├── utils/
│   │   ├── path_utils.py     # Path validation and normalization
│   │   ├── document_utils.py # Document handling utilities
│   │   └── __init__.py
│   ├── tools/                # Tool implementations (future phases)
│   ├── resources/            # MCP resource providers
│   └── __init__.py
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── test_server.py        # Server tests
├── pyproject.toml            # Project metadata and dependencies
├── setup.sh                  # Environment setup script
├── run.sh                    # Server launch script
├── claude_desktop_config.json # Claude configuration example
└── README.md                 # This file

支持的文档格式

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

局限性和未来工作

当前限制

基本合并字段处理（不支持完整字段代码）
简化图像定位
无需高级表格操作
无文档比较

计划中的增强功能

第6阶段：高级文本格式（字体、颜色、对齐方式）
第7阶段：完成表格操作
第8阶段：文件结构（章节、页眉、页脚、目录）
第9阶段：文件分析和统计
第10阶段：格式转换（PDF、Markdown、TXT）
第11阶段：批量操作
第12阶段：MCP资源端点

安全考虑

此服务器专为本地使用而设计。部署到生产环境或通过网络公开时：

认证：实现OAuth2或JWT令牌验证
授权：按作用域限制文件访问
速率限制：实施费率限制，防止滥用
审计日志：记录所有文档访问和修改
网络安全：使用TLS/SSL进行网络通信
文件验证：扫描文档以查找恶意软件

故障排除

虚拟环境问题

# Recreate virtual environment
rm -rf venv/
./setup.sh

未安装依赖项

# Update pip
source venv/bin/activate
pip install --upgrade pip

# Install with uv
uv sync --upgrade

服务器无法启动

# Check Python version
python3 --version  # Should be 3.10+

# Check logs
cat logs/docx_mcp_*.log

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

代码遵循PEP-8风格指南
所有测试均通过
新功能包括测试
文档已更新

支持

对于问题或疑问：

检查登录 logs/ 目录
验证文件路径是否正确
确保文档格式得到支持
查看错误消息以获取指导

使用FastMCP和python-docx构建，用于全面的Word文档管理。