MCP server for XRechnung and ZUGFeRD

Endpoint and package

The server runs hosted at this address (Streamable HTTP), and as an npm package for clients that start servers as a local process (stdio). Both offer the same tools.

Hosted

https://normapi.com/mcp

Local (stdio)

npx -y @normapi/mcp

Connect

Clients with connectors need only the address; the first time you generate an invoice, the client signs you in to NormAPI with OAuth. Clients with a config file can take your API key as a header instead.

Claude (claude.ai and Desktop): Settings → Connectors → Add custom connector, and paste the address.
ChatGPT: in developer mode, create a custom connector with this address and OAuth authentication.

Claude Code

claude mcp add --transport http normapi https://normapi.com/mcp

# or with your key instead of OAuth:
claude mcp add --transport http normapi https://normapi.com/mcp \
  --header "Authorization: Bearer nk_live_…"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "normapi": {
      "url": "https://normapi.com/mcp",
      "headers": { "Authorization": "Bearer nk_live_…" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "normapi": { "type": "http", "url": "https://normapi.com/mcp" }
  }
}

Any stdio client (e.g. claude_desktop_config.json)

{
  "mcpServers": {
    "normapi": {
      "command": "npx",
      "args": ["-y", "@normapi/mcp"],
      "env": { "NORMAPI_API_KEY": "nk_live_…" }
    }
  }
}

Tools

Three tools, each with a structured result and a text version for models that read only text.

Tool	What it does	Account
`validate_invoice`	Checks an XRechnung (UBL or CII, as text) or a ZUGFeRD/Factur-X PDF (base64) against the official KoSIT rules. Returns the verdict, the rule set version and every finding; every business-rule finding carries an explanation: what the rule requires, why it typically fires, how to fix it.	no
`generate_invoice`	Produces an XRechnung (UBL or CII) or a ZUGFeRD PDF from invoice data. Totals are computed server-side in decimal arithmetic, and the document is validated before it is returned. Data the rules do not permit is refused with the broken rules and how to fix each — and not counted.	yes, counts against the allowance
`explain_rule`	Explains a rule by its code (BR-DE-15, BR-CO-10, PEPPOL-EN16931-R010 …), with a link to its full page.	no

Sign-in and keys

Three ways in, depending on the client:

OAuth 2.1 (Claude, ChatGPT and other connectors): you sign in to NormAPI and allow the connection. It gets an API key of its own, named after the app (mcp-claude-…). Revoke that key under API keys and the app is disconnected at once.
An API key as a header (Claude Code, Cursor, VS Code): Authorization: Bearer nk_live_… — the same key as for the REST API.
stdio: the key in the environment variable NORMAPI_API_KEY.

Create an API key

Limits and privacy

The same rules as the REST API:

Documents up to 5 MB. Calls without a key are under the API’s anonymous limits, calls with one under that key’s.
Every generated invoice counts against the monthly allowance (25 free); validation never does.
Invoices are processed in memory and never stored — by the MCP server neither.
Technical validation, not tax or legal advice.

To the API documentation