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.
https://normapi.com/mcpnpx -y @normapi/mcpConnect
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): Customize → Connectors → Add → Add custom connector, and paste the address. Step by step, with pictures.
- ChatGPT: Plugins → search for NormAPI → “NormAPI – XRechnung & ZUGFeRD” → Install plugin, no address needed. In developer mode, Plugins → Add → Add custom MCP server also works, with this address and “OAuth or no authentication”. Step by step, with pictures.
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_…"{
"mcpServers": {
"normapi": {
"url": "https://normapi.com/mcp",
"headers": { "Authorization": "Bearer nk_live_…" }
}
}
}{
"servers": {
"normapi": { "type": "http", "url": "https://normapi.com/mcp" }
}
}{
"mcpServers": {
"normapi": {
"command": "npx",
"args": ["-y", "@normapi/mcp"],
"env": { "NORMAPI_API_KEY": "nk_live_…" }
}
}
}Tools
Four 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 |
parse_invoice | Reads a received e-invoice — XML as text or a ZUGFeRD/Factur-X PDF (base64) — into structured data: the invoice in exactly the shape generate_invoice takes, the amounts as the document states them, and every value it did not carry, by path. validate: true adds the verdict. | no |
generate_invoice | Produces an XRechnung (UBL or CII) or a ZUGFeRD PDF from invoice data; with profile=en16931, an EN 16931 invoice for a business, without Leitweg-ID, contact person and electronic addresses. A ZUGFeRD PDF is printed on your account’s letterhead automatically when it has one (uploaded at normapi.com/konto/briefkopf); letterhead=none gives NormAPI’s standard layout. 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-…). Disconnect it on the account overview under “Connected apps”, or revoke the key under API keys, and the app loses access 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.
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 (50 free); validating and reading never do.
- Invoices are processed in memory and never stored — by the MCP server neither.
- Technical validation, not tax or legal advice.