eliDocs
/
Integrations

MCP server

The Beliq MCP server lets AI clients like Claude and Cursor validate, parse, generate, and convert e-invoices against authority-pinned rules and explain what fails.

Available

An MCP server for Beliq. It lets MCP clients (Claude Desktop, Claude Code, Cursor, and others) validate, parse, generate, and convert e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS, and other UBL/CII documents) against authority-pinned rules, and explain exactly what fails.

Tools

  • beliq_validate_einvoice: validate a UBL/CII XML invoice (inline or by file path) or a Factur-X/ZUGFeRD PDF (by file path). Returns the verdict, the detected format and profile, the ruleset (Schematron) version it checked against, and every error and warning with its rule id, severity, location, and message.
  • 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 and the extracted invoice (number, dates, currency, seller, buyer, lines, totals, and any national extensions present).
  • beliq_generate_einvoice: generate a compliant document from an EN 16931 invoice object. Set standard to xrechnung, zugferd, facturx, or peppol-bis. XML output comes back inline; PDF output is written to the outputPath you provide. By default the result is validated before it is returned (verify), so a non-compliant document fails rather than coming back.
  • beliq_convert_einvoice: convert a document from one EN 16931 format to another. Set targetFormat to cii, ubl, xrechnung, peppol-bis, facturx, or zugferd. An XML target comes back inline; a PDF target is written to outputPath. The result reports the resolved source and target formats and any elements the conversion could not carry across.
  • 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.

Install

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.

Configuration

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

Variable Required Default Description
BELIQ_API_KEY yes (none) API key from the Beliq dashboard.
BELIQ_AUTH no header How the key is sent: header (X-API-Key) or bearer (Authorization: Bearer).
BELIQ_BASE_URL no https://api.beliq.eu Override for a self-hosted deployment; defaults to the production API.

Client setup

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:

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

Reading a result

beliq_validate_einvoice returns a short text verdict plus a structured result:

  • valid is true only when there are no errors; warnings do not make a document invalid.
  • format and profileDetected report the detected syntax and business profile.
  • schematronVersion is the exact ruleset revision the check ran against.
  • errors[] and warnings[] each carry ruleId, severity, location (an XPath when available), and message.

beliq_parse_einvoice returns the detected format and profileDetected plus the extracted invoice object (the EN 16931 fields present in the document).

beliq_generate_einvoice returns the output kind (xml or pdf), the contentType, and the schematronVersion the document was checked against. XML output is also returned inline as xml; PDF output (and XML when you set outputPath) is written to disk, and the result reports outputPath and bytesWritten. The tool never overwrites an existing file, so point outputPath at a path that does not exist yet.

beliq_convert_einvoice returns the output kind, the resolved sourceFormat and targetFormat, and lostElementsCount with lostElements for anything the conversion could not carry across. An XML target comes back inline as xml; a PDF target (facturx / zugferd) is written to outputPath. Like generate, it never overwrites an existing file.

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.

See also