MCP server for AI assistants

An MCP server over the Invoiceflair e-invoicing engine. It makes the same tools the portal and the workstation run available to an AI assistant — Claude Desktop, VS Code, Claude Code, or any other client that speaks the Model Context Protocol.

Everything runs on the user’s own machine. The server is started by the client as a child process and speaks JSON-RPC over stdin/stdout. There is no network access, no API key and no quota — the sole exception is the VAT ID check, which calls the European Commission’s VIES service and says so.

Why this makes sense

A language model cannot compute an EN 16931 validation and cannot write a ZUGFeRD hybrid PDF. What it can do well is decide that something now needs validating, converting or creating, and gather the data for it. The two capabilities complement each other; neither replaces the other.

The nine tools

Tool	What it does	Writes?
validate_invoice	validates an invoice against EN 16931 or the rules of its national format	no
read_invoice	reads an invoice (XML or hybrid PDF) as hub JSON	a result file
convert_invoice	converts between the formats; validates the result as well	a result file
create_invoice	produces an invoice from JSON data	a result file
create_invoice_pdf	produces a ZUGFeRD/Factur-X hybrid PDF	a result file
extract_from_pdf	retrieves the embedded invoice from a hybrid PDF	a result file
combine_to_hybrid_pdf	visual PDF + invoice XML → hybrid PDF	a result file
list_formats	names the valid format tokens	no
validate_vat	checks a VAT ID through VIES	no

There is also a resource invoice://schema/create-input: the JSON schema of the creation input, with the EN 16931 references (BT/BG) on every field. It is generated from the engine’s own type and therefore cannot go stale.

Why the schema is a resource and not a tool schema

It is around 25 KB and would otherwise be loaded into every conversation — including those where only validation happens.

File paths instead of contents

The server takes absolute file paths and returns results as files, not as content. There are two reasons for this:

1. Sending an invoice file of up to 15 MB base64-encoded through a model’s context window is expensive, and with a scanned PDF simply not viable.
2. Only this makes the tools chainable: the assistant passes the path from one tool unchanged into the next — create → validate → combine — without any document ever travelling through the conversation.

Every result comes back as a resource_link; small text results also sit alongside it in plain text up to 32 KB. Binary results such as PDF or XLSX never do.

Without a target path given, results land in a subfolder of the temp directory — the path is stated in the answer. An existing file is never overwritten.

Which formats

The same nine as in the portal, plus the ERP sources and some twenty non-European formats for reading. list_formats names the currently valid position — see also E-invoicing and its formats.

How to begin

1. Set up the server — configuration snippets per client
2. Switches, limits and pitfalls — in particular INVOICEFLAIR_MCP_ROOT