rechnungsapi-mcp

Give your AI assistant e-invoicing superpowers.
The official MCP server for RechnungsAPI: let AI agents create, validate and read ZUGFeRD and XRechnung invoices.

Germany's e-invoicing obligation (E-Rechnungspflicht) is being phased in, and structured invoices such as XRechnung and ZUGFeRD are becoming the standard. RechnungsAPI is the REST API that takes care of the hard parts. This server connects it to your AI assistant through the Model Context Protocol, so the assistant can do the e-invoicing work for you, right inside the conversation.

Start free · Documentation · Pricing · SDK for developers

Ask in plain language

You say	What happens
"Validate this XRechnung and tell me what is wrong."	validate_xrechnung_xml checks it against the schema and the business rules, and the assistant explains the findings
"Create an XRechnung for this order: customer, three line items, 19% VAT."	create_xrechnung builds the XML from the invoice data the assistant puts together from your description
"Read this invoice PDF and give me the data as JSON."	analyze_pdf_invoice extracts structured data from the PDF, scan or photo
"Turn this PDF invoice into a ZUGFeRD e-invoice."	create_zugferd_from_pdf takes the PDF or scan in and returns a validated ZUGFeRD PDF, in one step

Files travel as base64 text, which suits single invoices. For bulk or large-file workflows use the SDK or the REST API directly.

Connect in a minute

You need a RechnungsAPI token, and it is free to start: create an account, open Profile and copy the token. See Authentication for how it is sent.

Hosted by RechnungsAPI, nothing to install. Add this to your MCP client, for example as .mcp.json in your project for Claude Code:

{
  "mcpServers": {
    "rechnungsapi": {
      "type": "http",
      "url": "https://mcp.rechnungsapi.de/mcp",
      "headers": { "Authorization": "Bearer your-api-token" }
    }
  }
}

Or run it locally with npx (needs Node.js 20 or newer). The same mcpServers entry works for Claude Code and for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "rechnungsapi": {
      "command": "npx",
      "args": ["-y", "rechnungsapi-mcp"],
      "env": {
        "RECHNUNGSAPI_TOKEN": "your-api-token"
      }
    }
  }
}

It works with Claude Code, Claude Desktop and Open WebUI, and with any MCP client that speaks Streamable HTTP with a custom header, or stdio.

Why teams use it

• Nothing to install. Use the hosted server at mcp.rechnungsapi.de, or run the same server locally with one npx line.
• Your token, your data. Every request carries the caller's own token, so nothing is shared between customers. The server stores no invoices, and its logs hold request metadata only (path, status, timing), never invoice data, tool arguments or tokens.
• Complete. Ten tools cover creating, validating and reading e-invoices, including asynchronous analysis for big files.
• Built for Germany and the EU. RechnungsAPI is built for EN 16931, GoBD and GDPR, with data processed on German servers, and supports ZUGFeRD, XRechnung and Factur-X.
• Open source and typed. MIT licensed and built on the rechnungsapi-sdk.
• Free to start. Try it without a credit card.

Tools

Tool	Description
create_zugferd_invoice	Create a ZUGFeRD PDF/A-3 from structured invoice JSON + a visual PDF
create_xrechnung	Create an XRechnung XML from structured invoice JSON
create_zugferd_pdf	Embed an existing XRechnung XML into a visual PDF
extract_xrechnung_from_zugferd	Extract the embedded XRechnung XML from a ZUGFeRD PDF as JSON
validate_xrechnung_xml	Validate an XRechnung XML against schema and business rules
validate_zugferd_pdf	Validate a ZUGFeRD PDF's embedded XML
analyze_pdf_invoice	Extract structured invoice JSON from a scanned/PDF invoice
analyze_pdf_invoice_async_submit / analyze_pdf_invoice_async_status	Async analysis for large files
create_zugferd_from_pdf	Convert a PDF/scan directly into a validated ZUGFeRD PDF

Each tool maps to one RechnungsAPI endpoint. The API documentation shows its request and response.

Documentation

• API documentation: every endpoint these tools call, with request, response and error codes (English and German)
• MCP server & SDK guide: how to connect AI clients to RechnungsAPI's hosted MCP server
• Authentication: where your API token comes from and how it is sent
• Invoice object reference: the fields the create_* tools expect in invoice (EN 16931 business terms)
• Errors: what the HTTP status codes and validation results mean

Environment variables (local mode)

Variable	Required	Description
RECHNUNGSAPI_TOKEN	Yes	Your RechnungsAPI Bearer token
RECHNUNGSAPI_BASE_URL	No	Override the gateway base URL (e.g. a staging or self-hosted gateway)
RECHNUNGSAPI_V2_BASE_URL	No	Override the v2 analyzer host

Self-hosting (Streamable HTTP)

By default this runs as a local stdio process, spawned per-user by their own AI client. That is what the npx setup above does, and it is the standard way MCP servers work. If instead you want to run one shared, always-on server that many users connect to remotely (no local install on their end at all, just a URL), use the HTTP mode.

The key architectural difference: stdio mode reads one fixed RECHNUNGSAPI_TOKEN from the environment at startup and reuses it for the whole process's life. HTTP mode instead reads each request's own token from its Authorization: Bearer <token> header, and builds a fresh, isolated client per request, so many different customers can safely share the same running server, each authenticated as themselves, never seeing each other's data.

Run it

yarn build
yarn start:http   # listens on $PORT, default 3939

Or via Docker:

docker build -t rechnungsapi-mcp .
docker run -p 127.0.0.1:3939:3939 rechnungsapi-mcp

Or with Docker Compose: docker compose up -d builds the image from this repo's Dockerfile (see docker-compose.yml).

Or as a Portainer stack: paste deploy/portainer-stack.yml into Stacks → Add stack → Web editor and deploy. It needs no build, because the container installs the published package from npm when it starts. To upgrade, change the version in its command and redeploy. (Use this file rather than docker-compose.yml in the web editor: there is no build context there for build: . to use.)

No RECHNUNGSAPI_TOKEN is configured on the server itself in this mode, because each caller supplies their own.

Server settings (HTTP mode)

Variable	Default	Description
PORT	3939	Port to listen on
MAX_BODY_MB	64	Largest accepted request body. Invoices arrive as base64 PDFs, so this is generous; anything larger is answered with 413.
RECHNUNGSAPI_BASE_URL	production gateway	Override the gateway base URL
RECHNUNGSAPI_V2_BASE_URL	production v2 host	Override the v2 analyzer host

Endpoints

Endpoint	Description
POST /mcp	The MCP endpoint. Requires Authorization: Bearer <caller's own RechnungsAPI token>.
GET /health	Health check (used by Docker's HEALTHCHECK / Portainer / load balancers). No auth required.
GET /	A small page that says what the server is and links the documentation.

Putting it behind a domain

See deploy/nginx-mcp.conf for a ready-to-use reverse proxy config (e.g. for mcp.rechnungsapi.de), including the settings needed so nginx doesn't buffer or break the SSE streaming responses. Pair it with certbot --nginx -d mcp.rechnungsapi.de for HTTPS, which is required in practice since real API tokens travel in every request. Also redirect plain HTTP to HTTPS (Nginx Proxy Manager: enable Force SSL on the proxy host), so a mistyped http:// URL never sends a token unencrypted.

Two proxy settings matter for real invoices. First, the body limit: nginx refuses request bodies over 1 MB by default (413, before the request reaches this server), so the shipped config sets client_max_body_size 64m to match MAX_BODY_MB. In Nginx Proxy Manager, add the same line under the proxy host's Advanced tab if you ever see those 413s. Second, the timeout: analysing a large scan can take a while, so the shipped config raises proxy_read_timeout; clients can also use the async tools for big files.

Troubleshooting a client that "can't reach" the server

Every request is logged, so start with the container logs while the client tries to connect:

docker logs -f rechnungsapi-mcp
# [http] POST /mcp -> 200 12ms auth=yes rpc=initialize proto=- ua="..."

What you see	What it means
Nothing at all	The request never arrived. Check DNS, the reverse proxy and firewalls. curl https://your-host/health from outside should return {"ok":true,...}.
401 ... auth=no	The client isn't sending an Authorization header. The connector's auth mode is probably set to OAuth/none instead of a Bearer/API-key header.
401 ... auth=yes	The header arrived but the token is empty or wrong. Copy it again from your profile (see Authentication). The Bearer prefix is optional, a bare token is accepted.
GET /mcp -> 405	Expected. This server doesn't offer the optional server-push SSE stream; compliant clients continue over POST.
OPTIONS /mcp -> 204	Expected: a browser-based client's CORS preflight.
POST /mcp -> 413	The request body exceeded MAX_BODY_MB.
The client gets 413 Request Entity Too Large (an HTML page) but the log shows nothing	The reverse proxy refused the body before it reached this server. nginx's default limit is 1 MB, so set client_max_body_size 64m; (see deploy/nginx-mcp.conf).
POST /mcp -> 400	The body wasn't valid JSON (JSON-RPC parse error -32700).

Log lines record JSON-RPC method names only (e.g. rpc=tools/call), never arguments, so invoice data and tokens don't end up in your logs.

Start free

RechnungsAPI is free to start, with no credit card required. Create your account, copy your token and connect your assistant in minutes. Questions about plans, integration or your project? Talk to us or write to [email protected].

Development

yarn install
yarn typecheck
yarn test    # builds first, then runs the stdio and HTTP suites against a stub API
yarn build

Test locally with the MCP Inspector:

RECHNUNGSAPI_TOKEN=your-token yarn inspect

Note: @modelcontextprotocol/sdk is pinned to an exact version rather than ^1.x. This server is reachable from the internet, so the library only changes after the test suite has run against the new version. Releases before 1.26.0 have published security advisories (they show up in npm audit), so don't go back to an older one.

Found a security problem? Please read SECURITY.md.

License

MIT © RechnungsAPI · rechnungsapi.de · [email protected]