# Dokmatiq DocGen MCP Server

<!-- mcp-name: io.github.dokmatiq/docgen -->

MCP (Model Context Protocol) server that exposes the [Dokmatiq DocGen](https://dokmatiq.com) document generation API as tools for AI assistants like Codex, Claude Code, Claude Desktop, Cursor, Continue, Cline, and Hermes.

Use it to generate PDFs, DOCX/ODT documents, Excel workbooks, invoices, e-invoices (ZUGFeRD/XRechnung/Factur-X), receipt exports, signed PDFs, PDF forms, and documents on company letterhead (Briefpapier/Firmenpapier).

## Setup

### Prerequisites

- Python 3.11+
- DocGen API key

### Installation

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

The package requires Python 3.11 or newer. On macOS, the system or Xcode-provided `python3` can be too old; use Homebrew Python, pyenv, uv, or another Python 3.11+ runtime if `pip` cannot find a compatible package.

`pip install --user` commonly installs the `docgen-mcp` command into `~/.local/bin`. If your MCP client cannot find `docgen-mcp`, add `~/.local/bin` to `PATH` or use the absolute command path in your MCP config.

Or install from source:

```bash
cd mcp
pip install -e .
```

### Configuration

Set your API key as an environment variable:

```bash
export DOCGEN_API_KEY=dk_live_xxx
```

Optionally override the base URL:

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

## Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

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

Or using `uvx`:

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

## Usage with Claude Code

```bash
claude mcp add docgen -- docgen-mcp
```

Set the API key in your environment or `.env` file.

## Usage with Codex

Install the companion skill:

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

Then configure an MCP server named `docgen` using either `docgen-mcp`, an absolute path such as `/Users/you/.local/bin/docgen-mcp`, or `uvx dokmatiq-docgen-mcp`. Make sure `DOCGEN_API_KEY` is available to the server process.

## Usage with Hermes

Add the MCP server to your Hermes config (`~/.hermes/config.yaml`):

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

Replace `dk_live_xxx` with your Dokmatiq API key.

## Environment Variables in MCP Configs

Do not use shell placeholders such as `${DOCGEN_API_KEY}` inside JSON MCP config files unless your specific client documents that it expands them. Many MCP clients pass that value literally to the server, which causes authentication to fail.

## Available Tools

### Document Generation

| Tool | Description |
|------|-------------|
| `generate_pdf_from_html` | Convert HTML to PDF |
| `generate_pdf_from_markdown` | Convert Markdown to PDF |
| `generate_document` | Generate with template, fields, watermark, output format |
| `compose_document` | Compose multi-part document from sections |
| `create_invoice` | Create ZUGFeRD-compliant invoice PDF |

### PDF Tools

| Tool | Description |
|------|-------------|
| `merge_pdfs` | Merge multiple PDFs into one |
| `extract_text_from_pdf` | Extract all text content |
| `get_pdf_metadata` | Get title, author, page count |
| `convert_to_pdfa` | Convert to PDF/A archival format |
| `rotate_pdf` | Rotate pages |

### PDF Forms

| Tool | Description |
|------|-------------|
| `inspect_pdf_form` | List form fields with types and values |
| `fill_pdf_form` | Fill form fields |

### Digital Signatures

| Tool | Description |
|------|-------------|
| `sign_pdf` | Digitally sign with PKCS#12 certificate |
| `verify_pdf_signatures` | Verify existing signatures |
| `list_certificates` | List uploaded certificates |

### Templates & Fonts

| Tool | Description |
|------|-------------|
| `list_templates` | List uploaded templates |
| `upload_template` | Upload ODT/DOCX template |
| `delete_template` | Delete a template |
| `list_fonts` | List uploaded fonts |

### Preview

| Tool | Description |
|------|-------------|
| `preview_pdf_page` | Render page as PNG image |
| `get_pdf_page_count` | Get total page count |

### Excel Workbooks

| Tool | Description |
|------|-------------|
| `generate_excel` | Generate styled XLSX from structured JSON (sheets, columns, formulas, styling, freeze panes) |
| `csv_to_excel` | Convert CSV to formatted Excel with auto-filter and styled headers |
| `excel_to_csv` | Extract Excel sheet data as CSV |
| `excel_to_json` | Extract Excel sheet data as structured JSON with typed values |
| `fill_excel_template` | Fill Excel template with values at named cells and ranges |
| `inspect_excel` | Inspect workbook metadata (sheet names, row/column counts, named ranges) |

### E-Invoicing

| Tool | Description |
|------|-------------|
| `validate_zugferd` | Validate ZUGFeRD compliance |
| `extract_zugferd` | Extract invoice data from ZUGFeRD PDF |
| `validate_xrechnung` | Validate XRechnung XML |
| `parse_xrechnung` | Parse XRechnung into structured data |
| `detect_xrechnung` | Detect XRechnung format |

### Receipt Recognition (AI-Powered)

| Tool | Description |
|------|-------------|
| `extract_receipt` | Extract structured data from receipt image (vendor, totals, VAT, line items, SKR03/04 account) |
| `extract_receipt_async` | Submit receipt for async extraction with optional webhook |
| `get_receipt_job` | Check async extraction job status |
| `get_receipt_job_result` | Get extraction result of completed job |
| `list_receipt_jobs` | List all async receipt jobs |
| `receipt_to_document` | Extract receipt and generate expense report (PDF/DOCX/ODT) |
| `export_receipts_csv` | Export receipts as DATEV-compatible CSV |
| `export_receipts_xlsx` | Export receipts as Excel workbook |

## Example Prompts

Once connected, you can ask Claude:

- "Generate a PDF from this HTML: `<h1>Hello World</h1>`"
- "Create an invoice for ACME GmbH to Kunde AG for 8 hours of consulting at 120€/hour"
- "Merge these two PDFs together"
- "Extract the text from this PDF"
- "Fill the form fields name=Max and date=12.04.2026 in this PDF"
- "Extract the data from this receipt image -- I need vendor, total, and VAT breakdown"
- "Analyze these receipts and export them as a DATEV CSV"
- "Turn this receipt photo into an expense report PDF"

## License

MIT