rechnungsapi-mcp

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

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

Related MCP server: Scribo MCP Server

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

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)

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)

Endpoints

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="..."

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 support@rechnungsapi.de.

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 · support@rechnungsapi.de