A MCP (Model Context Protocol) service for Word document processing, providing document structure extraction, content modification and file management capabilities.
一个基于 MCP (Model Context Protocol) 的 Word 文档处理服务，提供文档结构提取、内容修改和文件管理功能。
# 在项目目录下运行
uvx --from . docx-mcp
# 或使用 uv tool run
uv tool run --from . docx-mcp
# 发布到 PyPI 后可以直接运行
uvx docx-mcp
# 使用 uv 安装依赖
uv sync
# 或使用 pip 从 pyproject.toml 安装
pip install -e .
在 Cursor 的 mcp.json 配置文件中添加以下配置：
{
"mcpServers": {
"docx_filler_service": {
"command": "cmd",
"args": [
"/c",
"uvx",
"--from",
"C:\\Users\\你的用户名\\Desktop\\docx_mcp",
"docx-mcp"
]
}
}
}
{
"mcpServers": {
"docx_filler_service": {
"command": "cmd",
"args": [
"/c",
"uvx",
"docx-mcp"
]
}
}
}
{
"mcpServers": {
"docx_filler_service": {
"command": "cmd",
"args": [
"/c",
"uv",
"--directory",
"C:\\Users\\你的用户名\\Desktop\\docx_mcp",
"run",
"main.py"
]
}
}
}
# 使用 uvx 从本地运行（当前推荐）
uvx --from . docx-mcp
# 使用 uvx 从 PyPI（发布后）
uvx docx-mcp
# 使用 uv 运行（开发模式）
uv run main.py
# 或直接运行
python main.py
如果您想要发布包以便全局使用 uvx：
# 1. 运行凭证配置脚本
python setup_pypi_credentials.py
# 2. 运行发布脚本
python publish.py
# 1. 设置 PyPI 凭证
$env:TWINE_USERNAME = "your-pypi-username"
$env:TWINE_PASSWORD = "your-pypi-password"
# 2. 构建包
uv build
# 3. 发布到 PyPI
pip install twine
twine upload dist/*
发布后，任何人都可以直接使用：
uvx docx-mcp
extract_document_structure(document_url: str) -> Dict
从 URL 下载 .docx 文件并提取其结构，为每个元素分配唯一 ID。
参数:
document_url: .docx 文件的 URL 链接返回: 包含文档结构的字典，每个元素都有唯一的 ID
apply_modifications_to_document(
original_file_content_base64: str,
patches_json: str
) -> str
将一系列修改应用到 .docx 文件，返回修改后的文件内容。
参数:
original_file_content_base64: 原始 .docx 文件的 Base64 编码patches_json: JSON 格式的修改指令列表示例修改指令:
[
{
"element_id": "p_0",
"new_content": "新的段落内容"
},
{
"element_id": "table_0_cell_0_0",
"new_content": "新的表格单元格内容"
}
]
get_modified_document(
original_file_content_base64: str,
patches_json: str
) -> str
apply_modifications_to_document 的别名，用于更清晰地表达获取最终结果的意图。
prepare_document_for_download(
original_file_content_base64: str,
patches_json: str
) -> Dict
将修改后的文档上传到阿里云 OSS，返回下载链接。
返回示例:
{
"success": true,
"download_url": "https://ggb-lzt.oss-cn-shenzhen.aliyuncs.com/modified_document_xxx.docx",
"file_name": "modified_document_xxx.docx"
}
process_document_from_url(
document_url: str,
patches_json: str
) -> Dict
直接从 URL 下载文档，应用修改，然后上传到 OSS。
docx_mcp/
├── core/ # 核心功能模块
│ ├── docx_processor.py # 文档处理器
│ └── models.py # 数据模型定义
├── dist/ # 构建输出目录
│ ├── docx_mcp-0.1.0-py3-none-any.whl
│ └── docx_mcp-0.1.0.tar.gz
├── main.py # MCP 服务主入口
├── pyproject.toml # 项目配置和依赖定义
├── requirements.txt # 备用依赖文件（兼容性）
├── uv.lock # uv 锁定文件
├── LICENSE # MIT 许可证
├── PUBLISH.md # 发布指南
├── PRE_PUBLISH_CHECKLIST.md # 发布前检查清单
├── READY_TO_PUBLISH.md # 发布准备说明
├── setup_pypi_credentials.py # PyPI 凭证配置脚本
├── publish.py # 自动化发布脚本
├── env.example # 环境变量配置模板
└── README.md # 项目文档
推荐使用环境变量配置 OSS 访问信息。复制 env.example 文件并重命名为 .env，然后填入您的实际配置：
# 复制配置模板
cp env.example .env
在 .env 文件中设置：
OSS_ACCESS_KEY=your_access_key_here
OSS_SECRET_KEY=your_secret_key_here
OSS_BUCKET_NAME=your_bucket_name
OSS_DOMAIN=https://your-bucket.oss-cn-shenzhen.aliyuncs.com/
或者在系统环境变量中设置：
# Windows PowerShell
$env:OSS_ACCESS_KEY = "your_access_key_here"
$env:OSS_SECRET_KEY = "your_secret_key_here"
$env:OSS_BUCKET_NAME = "your_bucket_name"
$env:OSS_DOMAIN = "https://your-bucket.oss-cn-shenzhen.aliyuncs.com/"
# PyPI 发布凭证（可选）
$env:TWINE_USERNAME = "your-pypi-username"
$env:TWINE_PASSWORD = "your-pypi-password"
# Linux/macOS
export OSS_ACCESS_KEY="your_access_key_here"
export OSS_SECRET_KEY="your_secret_key_here"
export OSS_BUCKET_NAME="your_bucket_name"
export OSS_DOMAIN="https://your-bucket.oss-cn-shenzhen.aliyuncs.com/"
# PyPI 发布凭证（可选）
export TWINE_USERNAME="your-pypi-username"
export TWINE_PASSWORD="your-pypi-password"
⚠️ 安全提示:
.env 文件已添加到 .gitignore 中项目使用 Pydantic 定义数据模型：
class DocumentPatch(BaseModel):
element_id: str # 元素唯一标识符
new_content: Any # 新内容（支持多种类型）
要添加新的文档处理功能：
core/docx_processor.py 中实现处理逻辑main.py 中使用 @mcp.tool() 装饰器注册新的 MCP 工具git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)本项目基于 MIT 许可证开源 - 查看 LICENSE 文件了解详情。
A: uvx 是用于运行独立 Python 工具的工具，类似 npx。它会自动处理依赖和环境隔离，更适合工具型应用。uv 主要用于项目依赖管理和开发。
A: 服务支持通过 Base64 编码处理大文件，但建议文件大小不超过 50MB。
A: 目前仅支持 .docx 格式（Office 2007+ 格式）。
A: 修改 main.py 中的 OSS_CONFIG 字典，或考虑使用环境变量。
A: 确保已安装 uv，然后 uvx 会自动可用。如果仍有问题，可以使用 uv tool run docx-mcp 替代。
💡 提示: 如有问题或建议，欢迎提交 Issue 或 Pull Request！
FAQs
A MCP (Model Context Protocol) service for Word document processing, providing document structure extraction, content modification and file management capabilities.
We found that docx-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Two npm packages masquerading as WhatsApp developer libraries include a kill switch that deletes all files if the phone number isn’t whitelisted.
Research
/Security News
Socket uncovered 11 malicious Go packages using obfuscated loaders to fetch and execute second-stage payloads via C2 domains.
Security News
TC39 advances 11 JavaScript proposals, with two moving to Stage 4, bringing better math, binary APIs, and more features one step closer to the ECMAScript spec.