Dokmatiq DocGen

Dokmatiq DocGen MCP 服务

MCP（Model Context Protocol）服务将 Dokmatiq DocGen 文档生成 API 作为工具提供给 Codex、Claude Code、Claude Desktop、Cursor、Continue、Cline 和 Hermes 等 AI 助手。

使用它可以生成 PDF、DOCX/ODT 文档、Excel 工作簿、发票、电子发票（ZUGFeRD/XRechnung/Factur-X）、收据导出文件、已签名 PDF、PDF 表单，以及带公司信头纸（Briefpapier/Firmenpapier）的文档。

设置

前置条件

• Python 3.11+
• DocGen API 密钥

安装

python3.11 -m pip install --user dokmatiq-docgen-mcp

该软件包需要 Python 3.11 或更高版本。在 macOS 上，系统或 Xcode 提供的 python3 版本可能过旧；如果 pip 找不到兼容的软件包，请使用 Homebrew Python、pyenv、uv 或其他 Python 3.11+ 运行时。

pip install --user 通常会将 docgen-mcp 命令安装到 ~/.local/bin。如果 MCP 客户端找不到 docgen-mcp，请将 ~/.local/bin 添加到 PATH，或在 MCP 配置中使用命令的绝对路径。

或者从源代码安装：

cd mcp
pip install -e .

运行测试

在仓库根目录中，使用已提交的锁定文件安装 MCP 服务 并运行其 stdio/客户端冒烟测试：

uv run --project mcp python -m unittest discover -s mcp/tests -v

配置

将 API 密钥设为环境变量：

export DOCGEN_API_KEY=dk_live_xxx

也可以选择覆盖基础 URL：

export DOCGEN_BASE_URL=https://custom.api.endpoint.com

在 Claude Desktop 中使用

将以下内容添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "docgen": {
      "command": "/Users/you/.local/bin/docgen-mcp",
      "env": {
        "DOCGEN_API_KEY": "dk_live_xxx"
      }
    }
  }
}

或使用 uvx：

{
  "mcpServers": {
    "docgen": {
      "command": "uvx",
      "args": ["dokmatiq-docgen-mcp"],
      "env": {
        "DOCGEN_API_KEY": "dk_live_xxx"
      }
    }
  }
}

在 Claude Code 中使用

claude mcp add docgen -- docgen-mcp

在环境或 .env 文件中设置 API 密钥。

在 Codex 中使用

安装配套技能：

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo dokmatiq/docgen-sdks \
  --path plugin/skills/dokmatiq-docgen

然后配置一个名为 docgen 的 MCP 服务，可使用 docgen-mcp、类似 /Users/you/.local/bin/docgen-mcp 的绝对路径，或 uvx dokmatiq-docgen-mcp。确保服务器进程可以获取 DOCGEN_API_KEY。

在 Hermes 中使用

将 MCP 服务添加到 Hermes 配置文件（~/.hermes/config.yaml）：

mcp_servers:
  docgen:
    command: "uvx"
    args: ["dokmatiq-docgen-mcp"]
    env:
      DOCGEN_API_KEY: "dk_live_xxx"

将 dk_live_xxx 替换为你的 Dokmatiq API 密钥。

MCP 配置中的环境变量

除非特定客户端的文档说明支持展开，否则不要在 JSON MCP 配置文件中使用 ${DOCGEN_API_KEY} 这类 Shell 占位符。许多 MCP 客户端会将该值原样传给服务，导致身份验证失败。

可用工具

文档生成

工具	说明
generate_pdf_from_html	将 HTML 转换为 PDF
generate_pdf_from_markdown	将 Markdown 转换为 PDF
generate_document	使用模板、字段、水印和输出格式生成文档
compose_document	根据多个章节组合文档
create_invoice	创建符合 ZUGFeRD 标准的发票 PDF

PDF 工具

工具	说明
merge_pdfs	将多个 PDF 合并为一个
extract_text_from_pdf	提取所有文本内容
get_pdf_metadata	获取标题、作者和页数
convert_to_pdfa	转换为 PDF/A 归档格式
rotate_pdf	旋转页面

PDF 表单

工具	说明
inspect_pdf_form	列出表单字段及其类型和值
fill_pdf_form	填写表单字段

数字签名

工具	说明
sign_pdf	使用 PKCS#12 证书进行数字签名
verify_pdf_signatures	验证现有签名
list_certificates	列出已上传的证书

模板和字体

工具	说明
list_templates	列出已上传的模板
upload_template	上传 ODT/DOCX 模板
delete_template	删除模板
list_fonts	列出已上传的字体

预览

工具	说明
preview_pdf_page	将页面渲染为 PNG 图像
get_pdf_page_count	获取总页数

Excel 工作簿

工具	描述
generate_excel	根据结构化 JSON 生成样式化 XLSX（工作表、列、公式、样式、冻结窗格）
csv_to_excel	将 CSV 转换为带自动筛选和样式化表头的 Excel
excel_to_csv	将 Excel 工作表数据提取为 CSV
excel_to_json	将 Excel 工作表数据提取为包含类型化值的结构化 JSON
fill_excel_template	使用值填充 Excel 模板中的命名单元格和区域
inspect_excel	检查工作簿元数据（工作表名称、行数/列数、命名区域）

电子发票

工具	描述
validate_zugferd	验证 ZUGFeRD 合规性
extract_zugferd	从 ZUGFeRD PDF 中提取发票数据
validate_xrechnung	验证 XRechnung XML
parse_xrechnung	将 XRechnung 解析为结构化数据
detect_xrechnung	检测 XRechnung 格式

收据识别（AI 驱动）

工具	描述
extract_receipt	从收据图片中提取结构化数据（供应商、总额、增值税、明细项、SKR03/04 科目）
extract_receipt_async	提交收据以进行异步提取，可选择提供 webhook
get_receipt_job	查看异步提取任务状态
get_receipt_job_result	获取已完成任务的提取结果
list_receipt_jobs	列出所有异步收据任务
receipt_to_document	提取收据并生成费用报告（PDF/DOCX/ODT）
export_receipts_csv	将收据导出为兼容 DATEV 的 CSV
export_receipts_xlsx	将收据导出为 Excel 工作簿

示例提示词

连接后，你可以向 Claude 提问：

• “根据这段 HTML 生成 PDF：<h1>Hello World</h1>”
• “为 ACME GmbH 开具发票，收件方为 Kunde AG，内容为 8 小时咨询服务，费率为 120€/小时”
• “合并这两个 PDF”
• “提取此 PDF 中的文本”
• “在此 PDF 中填写表单字段：姓名=Max，日期=12.04.2026”
• “从这张收据图片中提取数据——我需要供应商、总额和增值税明细”
• “分析这些收据，并将其导出为 DATEV CSV”
• “将这张收据照片转换为费用报告 PDF”

许可证

MIT