MCP server

The Beliq MCP server lets AI clients like Claude and Cursor validate, parse, generate and convert e-invoices, with the check depth the API states per verdict.

Available

An MCP server for Beliq. It lets MCP clients (Claude Desktop, Claude Code, Cursor, and others) validate e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS Billing 3.0, and the other formats the API carries) and explain exactly what fails, and parse, generate, and convert them. Each verdict shows the check depth the API states for it.

• Package: beliq-mcp on npm
• Source: github.com/beliq-eu/beliq-mcp

• beliq_validate_einvoice: validate an invoice XML (inline or by file path) or a Factur-X/ZUGFeRD PDF (by file path). Returns the verdict, how deep the check went, the detected format and profile, the versions of the rule packs and schemas it ran, and every error and warning with its rule id, severity, location, and message. For a PDF the verdict is about the embedded XML; the PDF itself is not checked.
• beliq_parse_einvoice: parse a UBL/CII XML invoice or a Factur-X/ZUGFeRD PDF into a structured EN 16931 invoice. Returns the detected format and profile, the extracted invoice (number, dates, currency, seller, buyer, lines and totals), and warnings that say what the document holds and the parsed invoice does not.
• beliq_generate_einvoice: generate a document from an EN 16931 invoice object. Set standard to xrechnung, zugferd, facturx, peppol-bis, fatturapa, facturae, eslog, or ksef. XML output comes back inline; PDF output is written to the outputPath you provide. By default the invoice XML is validated before it is returned (verify), so a document that fails its rules is refused rather than returned, and the text summary names how deep that check went. A ZUGFeRD or Factur-X PDF is returned only when veraPDF reports no violation of its PDF/A-3b profile in it (the PDF/A check on a hybrid PDF).
• beliq_convert_einvoice: convert a document from one EN 16931 format to another. Set targetFormat to cii, ubl, xrechnung, peppol-bis, facturx, or zugferd. From an XML source the result is XML, inline, for every target, facturx and zugferd included: an XML source is not wrapped into a hybrid PDF. From a hybrid PDF source, a facturx or zugferd target returns a PDF, written to outputPath: as sent, with only its annotation flags set as PDF/A asks, when its embedded XML already is the target, and otherwise re-wrapped around the converted XML; every other target returns XML. The result reports the resolved source and target formats and the losses the engine recorded. The API validates the converted XML before it returns it, and a conversion whose result fails is refused. For a facturx or zugferd target at profile en16931 the converted document carries the plain EN 16931 identifier, so it is checked as EN 16931 CII and against no Factur-X profile schema. The result carries no verdict and no check depth, so run beliq_validate_einvoice on the converted document to read its warnings. POST /v1/convert says what a returned document has and has not been checked for.
• beliq_check_account: verify the configured API key and report the plan and remaining quota. Calls GET /v1/me, which draws no quota; useful as a connection and credential smoke test.

The server is published to npm, so clients can run it with npx with no separate install step:

npx -y beliq-mcp

Requires Node.js 20.15 or newer.

The server is configured entirely through environment variables. Create an API key in the Beliq dashboard under Integration → API Keys.

Claude Code

claude mcp add beliq -e BELIQ_API_KEY=your-key -- npx -y beliq-mcp

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config). Cursor uses the same block in ~/.cursor/mcp.json or a project .cursor/mcp.json:

{
  "mcpServers": {
    "beliq": {
      "command": "npx",
      "args": ["-y", "beliq-mcp"],
      "env": {
        "BELIQ_API_KEY": "your-key"
      }
    }
  }
}

beliq_validate_einvoice returns a short text verdict plus a structured result:

• valid is the API’s verdict: the document passed the rule packs and schemas Beliq runs for its format, in the versions the result names. It does not mean every recipient, validation tool or tax authority accepts it. Warnings do not make a document invalid, with one case to read beside it: franceCtcBlockingRuleIds.
• verificationBadgeLabel is the check depth as English display text, and the text verdict prints it beside VALID or INVALID. How verification works says what each depth means. Where the API sends no label, the text says check depth not stated and names no depth. verificationBadge and verificationTier are the ids behind the label.
• franceCtcBlockingRuleIds lists the BR-FR-CTC rule ids the document trips. The API reports them beside valid, also where valid is true, and the text verdict then leads with them. The result stays a normal result, not a tool error. Warnings are not all optional says why they matter.
• pdfInput is present when the document was a PDF: it says which embedded file the verdict is about, and its containerChecked is always false, because the PDF itself is not checked.
• format and profileDetected report the detected syntax and business profile.
• schematronVersion is the Schematron revision the check ran against, where a Schematron ran. The versions of the other rule packs and schema bundles come in fields of their own, each present only when it applies.
• errors[] and warnings[] each carry ruleId, severity, location (an XPath when available), and message. errorCount and warningCount are their lengths.

The structured result carries every field of the API’s validation result.

beliq_parse_einvoice returns a short text summary plus a structured result:

• format, profileDetected and profileUrn report the detected syntax and profile; businessProcessId and franceCtcDetected are present when the document states them.
• invoice is the extracted invoice object, a subset of the EN 16931 fields, such as number, dates, currency, seller, buyer, lines and totals. A field the API holds no value for is left out.
• warnings says what the document holds and the parsed invoice does not: each entry has a code, a message, and, by code, a field, the terms (EN 16931 business term or group ids, such as BT-110 or BG-20) or the elements (paths with counts) concerned. The text summary lists them.

beliq_generate_einvoice returns a short text summary (with the XML document appended for XML output) plus a structured result:

• output is xml or pdf, as requested, and contentType is the matching media type (application/xml or application/pdf).
• xml is the generated document inline, present only for XML output.
• outputPath and bytesWritten are set when the document was written to disk: always for a PDF, and for XML when you set outputPath. The tool never overwrites an existing file, so point outputPath at a path that does not exist yet.
• pdfKind is present only for PDF output: hybrid (a PDF/A-3 with the XML embedded, for facturx and zugferd) or visualization (rendered pages with no XML inside, for xrechnung and peppol-bis, whose legal document stays the XML). See PDF output.
• schematronVersion is the ruleset (Schematron) revision the document was checked against.
• sha256 is the lowercase-hex SHA-256 of the returned document bytes, so sha256sum on the file at outputPath reproduces it.
• rulesetSha256 is one combined fingerprint of the rule artifacts the document was checked against, present when a ruleset ran.
• livemode is true for a blq_live_ key and false for a blq_test_ sandbox key, whose output is marked as a specimen and is not a production invoice.
• validationResult is the API’s verdict on the generated document, with the check depth in verificationBadgeLabel; the text summary names that depth. The verdict is about the invoice XML, so for a PDF the text says so and names the kind of PDF. With the default verify: true, a document that fails validation comes back as a tool error that lists the failed rules. With verify: false no ruleset runs: verified is false, valid is false, and errors/warnings are empty because nothing checked the document, not because it failed. The text then says not validated.

beliq_convert_einvoice returns a short text summary (with the XML document appended when XML came back) plus a structured result:

• output is what came back, read from the response: xml for every target when the source is XML, facturx and zugferd included, and pdf when a hybrid PDF source is converted to facturx or zugferd, whether it comes back as sent or re-wrapped. contentType is the matching media type (application/xml or application/pdf).
• xml is the converted document inline, present only when XML came back.
• outputPath and bytesWritten are set when the document was written to disk: always for a PDF, and for XML when you set outputPath. Like generate, it never overwrites an existing file.
• sourceFormat is the format the engine read, and targetFormat the format it produced (the targetFormat you asked for when the API does not name one).
• profileDetected is the profile the engine recognised on the source document, when it recognised one.
• lostElementsCount and lostElements count and name the source elements the engine recorded as having no equivalent in the target format. A loss the engine does not detect is not counted: the converters between CII and UBL are not checked field by field, so 0 means the engine recorded no loss, not that every field of the source arrived.

A PDF (Factur-X / ZUGFeRD) must be passed by file path to validate, parse, and convert, not inlined as text. The repo also ships a portable agent skill that teaches a model when to validate and how to report a verdict with its check depth.

• POST /v1/validate: the endpoint behind beliq_validate_einvoice.
• POST /v1/parse, POST /v1/generate, and POST /v1/convert: the endpoints behind parse, generate, and convert.
• How verification works: what the verdict means.
• Authentication: keys, quotas, and rate limits.