Skip to main content
Glama

docxtpl MCP Server

by z1w2r3
npmGitHub
Python
MIT License
374
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

📄 docxtpl MCP Server

基于模型上下文协议 (MCP) 的 Word 文档生成服务器，使用 Python 的 docxtpl 库提供强大的模板功能。

npm version Python Version MCP Protocol License

🚀 快速安装

方式 1：通过 Claude Code (推荐)

claude mcp add docxtpl npx docxtpl-mcp@latest

方式 2：直接使用 npx

# 无需安装，直接运行 npx docxtpl-mcp@latest

方式 3：全局安装

# 全局安装 npm install -g docxtpl-mcp # 运行 docxtpl-mcp

方式 4：手动配置 Claude Desktop

在 Claude Desktop 配置文件（~/.claude/config.json）中添加：

{ "mcpServers": { "docxtpl": { "command": "npx", "args": ["docxtpl-mcp@latest"] } } }

✨ 特性

  • 🚀 基于 MCP 协议 - 标准化的 AI 模型交互接口

  • 📝 强大的模板引擎 - 支持完整的 Jinja2 语法

  • 🔄 动态内容生成 - 条件渲染、循环、自定义过滤器

  • 📊 丰富的模板 - 内置发票、报告、合同、信函等模板

  • 🛠️ 易于扩展 - 简单添加自定义模板和功能

  • 🔒 安全可靠 - 完善的错误处理和输入验证

  • 📖 文档解析 - 支持解析 DOCX、PDF 和 Excel 文档,提取结构化内容

📋 目录

📋 前置要求

  • Node.js 14.0+ 和 npm（用于 npx）

  • Python 3.10+ （自动检测，如未安装会提示）

  • 支持 MCP 的 AI 客户端（如 Claude Desktop）

注意：首次运行时会自动安装 Python 依赖包，这可能需要几分钟时间。

📦 开发安装

如果您想从源代码运行或参与开发：

克隆仓库

# 克隆仓库 git clone https://github.com/yourusername/docxtpl-mcp.git cd docxtpl-mcp # 安装 Python 依赖 pip install -r requirements.txt # 创建示例模板 python create_templates.py # 直接运行服务器 python -m src.server

本地测试 npm 包

# 链接到全局 npm link # 测试运行 npx docxtpl-mcp

⚙️ 配置

环境变量

复制 .env.example 到 .env 并根据需要修改：

cp .env.example .env

可配置项：

变量

默认值

描述

TEMPLATE_DIR

templates

模板文件目录

OUTPUT_DIR

output

生成文档输出目录

MAX_FILE_SIZE_MB

50

最大文件大小限制（MB）

DEBUG

false

启用调试日志

Claude Desktop 配置

配置文件位置：

  • macOS/Linux: ~/.claude/config.json

  • Windows: %APPDATA%\Claude\config.json

使用 npm 包（推荐）

{ "mcpServers": { "docxtpl": { "command": "npx", "args": ["docxtpl-mcp@latest"] } } }

或从源代码运行

{ "mcpServers": { "docxtpl": { "command": "python", "args": ["-m", "src.server"], "cwd": "/path/to/docxtpl-mcp", "env": { "TEMPLATE_DIR": "templates", "OUTPUT_DIR": "output" } } } }

📖 使用方法

基本用法

  1. 列出可用模板

使用 list_templates 工具查看所有可用模板

  1. 生成文档

使用 generate_document 工具，提供模板名称和数据

  1. 验证模板

使用 validate_template 工具检查模板语法和所需变量

示例对话

用户： 帮我生成一份发票，客户是 ABC 公司，包含两个产品：软件许可证 10 个（单价 $99.99）和技术支持服务（$500）

AI： 我来帮您生成发票。让我使用发票模板创建文档...

[AI 调用 generate_document 工具]

AI： 发票已成功生成！

  • 📄 文件：invoice_20240928_143022.docx

  • 📁 位置：output/invoice_20240928_143022.docx

  • 💰 总计：$1,649.89（含10%税费）

文档解析示例

用户： 帮我解析这个 PDF 文件 /path/to/report.pdf,提取所有文本和表格

AI： 好的,我来解析这个 PDF 文档...

[AI 调用 parse_pdf_document 工具]

AI： PDF 文档解析成功！

  • 📄 文件：report.pdf

  • 📄 总页数：15 页

  • 📝 文本长度：12,450 字符

  • 📊 表格数：3 个

解析结果已转换为结构化 JSON 格式,包含每页的文本内容和表格数据。

用户： 解析这个 Excel 文件 /path/to/data.xlsx,我只需要 "销售数据" 工作表

AI： 好的,我来解析 Excel 文件...

[AI 调用 parse_excel_document 工具]

AI： Excel 文档解析成功！

  • 📄 文件：data.xlsx

  • 📊 工作表总数：5

  • 📋 已解析：销售数据

  • 💼 单元格数：1,200

  • 📐 公式数：15

解析结果包含工作表的所有单元格数据、公式和合并单元格信息。

🛠️ 可用工具

文档生成工具

1. generate_document

生成 Word 文档

参数：

  • template_name (string, 必需) - 模板文件名

  • context_data (object, 必需) - 填充模板的数据

  • output_name (string, 可选) - 输出文件名

示例：

{ "template_name": "invoice.docx", "context_data": { "company_name": "ABC Tech Inc.", "customer_name": "XYZ Corp", "items": [ { "description": "Software License", "quantity": 10, "unit_price": 99.99, "total": 999.90 } ], "total": 999.90 }, "output_name": "invoice_001" }

2. list_templates

列出所有可用的 Word 模板

参数： 无

返回： 模板列表及其信息

3. validate_template

验证模板并提取所需变量

参数：

  • template_name (string, 必需) - 模板文件名

返回： 模板中使用的变量列表

4. preview_template

使用示例数据预览模板

参数：

  • template_name (string, 必需) - 模板文件名

  • sample_data (object, 必需) - 示例数据

5. delete_document

删除生成的文档

参数：

  • document_id (string, 必需) - 文档 ID

6. list_documents

列出所有已生成的文档

参数： 无

文档解析工具

7. parse_docx_document

解析 DOCX 文档并提取结构化内容

参数：

  • file_path (string, 必需) - DOCX 文件的绝对路径

  • include_tables (boolean, 可选) - 是否提取表格 (默认: true)

返回： JSON 格式的结构化内容,包括:

  • 文档元数据 (作者、创建时间等)

  • 段落内容和样式

  • 表格数据

示例：

{ "file_path": "/path/to/document.docx", "include_tables": true }

8. parse_pdf_document

解析 PDF 文档并提取文本、表格和元数据

参数：

  • file_path (string, 必需) - PDF 文件的绝对路径

  • include_tables (boolean, 可选) - 是否提取表格 (默认: true)

  • pages (string, 可选) - 要解析的页面范围,如 "1-5" 或 "1,3,5" (默认: "all")

返回： JSON 格式的结构化内容,包括:

  • PDF 元数据

  • 每页的文本内容

  • 每页的表格数据

示例：

{ "file_path": "/path/to/document.pdf", "include_tables": true, "pages": "1-10" }

9. extract_text_from_document

快速提取文档纯文本 (支持 DOCX 和 PDF)

参数：

  • file_path (string, 必需) - 文档文件的绝对路径

返回： 文档的纯文本内容及统计信息

示例：

{ "file_path": "/path/to/document.docx" }

10. get_document_metadata

提取文档元数据信息

参数：

  • file_path (string, 必需) - 文档文件的绝对路径 (DOCX、PDF 或 Excel)

返回： JSON 格式的元数据,包括:

  • 文件基本信息 (文件名、大小、类型)

  • 作者、标题、主题等

  • 创建和修改时间

  • 文档统计信息

示例：

{ "file_path": "/path/to/document.pdf" }

11. parse_excel_document

解析 Excel 文档 (XLSX/XLS) 并提取结构化内容

参数：

  • file_path (string, 必需) - Excel 文件的绝对路径

  • sheet_name (string, 可选) - 指定要解析的工作表名称 (默认: 解析所有工作表)

  • include_formulas (boolean, 可选) - 是否包含单元格公式 (默认: true)

返回： JSON 格式的结构化内容,包括:

  • Excel 元数据 (创建者、修改时间等)

  • 工作表信息 (名称、行数、列数)

  • 单元格数据

  • 公式 (如果启用)

  • 合并单元格信息

示例：

{ "file_path": "/path/to/data.xlsx", "sheet_name": "销售数据", "include_formulas": true }

📋 模板示例

发票模板 (invoice.docx)

生成专业的商业发票：

  • 公司和客户信息

  • 商品明细表

  • 自动计算小计、税费和总计

  • 自定义备注和条款

报告模板 (report.docx)

创建结构化的业务报告：

  • 封面和目录

  • 执行摘要

  • 章节和子章节

  • 数据表格

  • 结论和建议

合同模板 (contract.docx)

生成法律合同文档：

  • 合同双方信息

  • 条款和子条款

  • 签名部分

  • 日期和编号

信函模板 (letter.docx)

创建正式商务信函：

  • 发件人和收件人信息

  • 主题行

  • 正文段落

  • 附件和抄送

📚 API 文档

资源 URI

  • template://{name} - 访问模板资源

  • document://{id} - 访问生成的文档

提示模板

  • invoice_generator - 发票生成提示

  • report_generator - 报告生成提示

自定义过滤器

  • currency - 格式化货币（例：1234.56 → $1,234.56）

  • date - 格式化日期（例：2024-09-28 → September 28, 2024）

🔧 开发指南

添加自定义模板

  1. 在 templates/ 目录创建新的 .docx 文件

  2. 使用 {{variable}} 语法插入变量

  3. 使用 {% for %} 进行循环

  4. 使用 {% if %} 进行条件判断

添加自定义过滤器

在 src/server.py 中注册新过滤器：

def my_custom_filter(value): return value.upper() jinja_env.filters['uppercase'] = my_custom_filter

运行测试

# 单元测试 pytest tests/ # 集成测试 pytest tests/integration/ # 覆盖率报告 pytest --cov=src tests/

🐛 故障排除

常见问题

Q: 模板找不到怎么办？ A: 确保模板文件在 templates/ 目录下，且文件扩展名为 .docx

Q: 生成的文档格式混乱？ A: 检查模板中的 Jinja2 语法是否正确，使用 validate_template 工具验证

Q: 如何处理大文件？ A: 调整 MAX_FILE_SIZE_MB 环境变量，或考虑分批生成

错误代码

代码

描述

解决方案

E001

模板未找到

检查模板路径和文件名

E002

语法错误

验证 Jinja2 语法

E003

数据类型错误

检查提供的数据格式

E004

文件大小超限

减少内容或调整限制

🤝 贡献

我们欢迎各种形式的贡献！

如何贡献

  1. Fork 本仓库

  2. 创建功能分支 (git checkout -b feature/amazing-feature)

  3. 提交更改 (git commit -m 'feat: add amazing feature')

  4. 推送到分支 (git push origin feature/amazing-feature)

  5. 开启 Pull Request

提交规范

使用 Conventional Commits 规范：

  • feat: 新功能

  • fix: 修复问题

  • docs: 文档更新

  • style: 代码格式

  • refactor: 代码重构

  • test: 测试相关

  • chore: 构建/工具

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

📞 联系方式

⭐ 如果这个项目对您有帮助，请给个 Star！

Made with ❤️ by the docxtpl-mcp team

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables Word document generation from templates using Jinja2 syntax and parsing of DOCX, PDF, and Excel files to extract structured content, metadata, and text.

  1. 🚀 快速安装
    1. 方式 1：通过 Claude Code (推荐)
    2. 方式 2：直接使用 npx
    3. 方式 3：全局安装
    4. 方式 4：手动配置 Claude Desktop
  2. ✨ 特性
    1. 📋 目录
      1. 📋 前置要求
        1. 📦 开发安装
          1. 克隆仓库
          2. 本地测试 npm 包
        2. ⚙️ 配置
          1. 环境变量
          2. Claude Desktop 配置
        3. 📖 使用方法
          1. 基本用法
          2. 示例对话
          3. 文档解析示例
        4. 🛠️ 可用工具
          1. 文档生成工具
          2. 2. list_templates
          3. 3. validate_template
          4. 4. preview_template
          5. 5. delete_document
          6. 6. list_documents
          7. 文档解析工具
        5. 📋 模板示例
          1. 发票模板 (invoice.docx)
          2. 报告模板 (report.docx)
          3. 合同模板 (contract.docx)
          4. 信函模板 (letter.docx)
        6. 📚 API 文档
          1. 资源 URI
          2. 提示模板
          3. 自定义过滤器
        7. 🔧 开发指南
          1. 添加自定义模板
          2. 添加自定义过滤器
          3. 运行测试
        8. 🐛 故障排除
          1. 常见问题
          2. 错误代码
        9. 🤝 贡献
          1. 如何贡献
          2. 提交规范
        10. 📄 许可证
          1. 🙏 致谢
            1. 📞 联系方式

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/z1w2r3/doc-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server