Skip to main content
Glama
beliq-eu

beliq-mcp

Official
by beliq-eu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

beliq-mcp

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

beliq produces and checks the compliant document. Transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.

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 was 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 (number, dates, currency, seller, buyer, lines, totals). Returns the detected format and profile and the extracted invoice.

  • beliq_generate_einvoice - generate a compliant document (XRechnung, ZUGFeRD, Factur-X, or Peppol BIS) from an EN 16931 invoice object. XML comes back inline; a PDF is written to the outputPath you give. Validates the result before returning by default (verify), so a non-compliant document fails rather than coming back.

  • beliq_convert_einvoice - convert a document from one EN 16931 format to another (targetFormat of cii, ubl, xrechnung, peppol-bis, facturx, or zugferd). An XML target comes back inline; a PDF target is written to outputPath. Reports 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.

Related MCP server: eleata e-invoice MCP server

Installation

Requires Node.js >= 20.15. Published to npm, so clients can run it with npx:

npx -y beliq-mcp

The server is configured entirely through environment variables (see below).

Configuration

Variable

Required

Default

Description

BELIQ_API_KEY

yes

-

API key from the beliq dashboard (API Keys).

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):

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

Cursor

Add to ~/.cursor/mcp.json (or a project .cursor/mcp.json) using the same mcpServers block shown for Claude Desktop.

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 (EN 16931 fields: number, dates, currency, seller, buyer, lines, totals, and any national extensions present).

beliq_generate_einvoice returns the output kind (xml or pdf), the contentType, and the schematronVersion the document was checked against. An XML document is also returned inline as xml; a PDF (and an XML when you set outputPath) is written to disk, and the call reports outputPath and bytesWritten. It does not overwrite an existing file: pick a path that does not exist.

beliq_convert_einvoice returns the output kind, the resolved sourceFormat and targetFormat, and lostElementsCount/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 documentPath for validate, parse, and convert, not inlined as text.

Agent skill

skill/SKILL.md is a portable agent skill that teaches a model when to validate, how to read errors/warnings, and how to report a verdict, using the tools above. Drop it into a skills directory for an agent that should validate invoices on request.

Development

This server depends on the published @beliq/sdk, which carries the request, transport, and result-shaping logic. package-lock.json is committed, and CI and the release build install from it with npm ci.

  • npm install

  • npm run build - compile to dist/

  • npm run typecheck

  • npm run lint

  • npm test - unit tests (result summary) and an in-memory MCP round-trip with a fake SDK client

  • BELIQ_API_KEY=your-key npm run test:integration - live smoke tests against the real API

  • npm run scrub:check - check for em-dashes in source and docs

Run the built server directly for a quick check:

BELIQ_API_KEY=your-key node dist/index.js

License

MIT

Available Tools

2 tools
beliq_check_accountbeliq: Check AccountA
Read-onlyIdempotent

Verify the configured beliq API key and report the plan and remaining quota. Calls GET /v1/me, which draws no quota. Use it as a connection and credential smoke test.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
okYes
planNo
statusYes
messageYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the HTTP endpoint (GET /v1/me) and that it draws no quota, adding valuable behavioral context beyond the annotations' readOnlyHint and idempotentHint. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first provides purpose and result, the second gives implementation detail and usage advice. Every word earns its place without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter smoke test tool with an output schema, the description sufficiently covers purpose, implementation, usage, and what is reported (plan and quota). It is complete for the task.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description logically does not need to elaborate on parameters. With 100% schema coverage of an empty object, a baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool verifies the API key and reports plan/quota. It distinguishes from the sibling 'beliq_validate_einvoice' by specifying a different purpose (credential smoke test vs. E-invoice validation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends use as a 'connection and credential smoke test'. It does not mention when not to use or alternatives, but the simple nature of the tool and differentiation from the sibling make this adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

beliq_validate_einvoicebeliq: Validate E-InvoiceA
Read-onlyIdempotent

Validate an EU electronic invoice against authority-pinned, drift-checked rules and report whether it is compliant. Accepts a UBL or CII XML document (inline via document, or a file via documentPath), or a Factur-X / ZUGFeRD PDF via documentPath. Returns the verdict (valid or not), the detected format and profile, the ruleset (Schematron) version it was checked against, and every error and warning with its rule id, severity, location, and message. beliq validates the compliant document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoSource syntax hint. 'auto' (default) detects CII vs UBL from the document.
documentNoThe invoice as XML text. Provide this OR documentPath, not both.
franceCtcNoApply the French CTC (Factur-X / Chorus Pro) rule overlay during validation.
documentPathNoPath to an invoice file on disk: a UBL/CII XML, or a PDF carrying embedded XML (Factur-X / ZUGFeRD). Provide this OR document.

Output Schema

ParametersJSON Schema
NameRequiredDescription
validYes
errorsYes
formatYes
warningsYes
errorCountYes
warningCountYes
profileDetectedNo
schematronVersionNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable behavioral details: rules are authority-pinned and drift-checked, returns verdict, format, profile, ruleset version, and detailed errors/warnings with rule id, severity, location, message.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, first covers purpose and output comprehensively, second clarifies boundaries. No redundancy, every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (4 params, output schema present), description covers input formats, action, and output summary. It also sets expectations about what the tool does not do (transmission/archiving). Return values are detailed in output schema, so not needed in description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameters are well-described in schema. Description adds context: 'auto' default for format, mutual exclusivity of document vs documentPath, and French CTC overlay. Slight improvement over schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'validate' with specific resource 'EU electronic invoice'. Specifies scope (authority-pinned, drift-checked rules) and output (compliance verdict). Distinguishes from sibling tool 'beliq_check_account' by focusing on invoice validation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the tool validates only, not for transmission/archiving/reporting. Describes accepted input types (UBL, CII, Factur-X/ZUGFeRD PDF). Lacks explicit when-not-to-use or direct comparison to sibling, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.1
    • First observedbeliq_check_account
    • First observedbeliq_validate_einvoice
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely different purposes: one is a simple credential and quota check, the other validates e-invoices. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent 'beliq_verb_noun' pattern (check_account, validate_einvoice), which is clear and predictable.

Tool Count3/5

With only two tools, the server feels very minimal. While the scope is limited to validation and account status, one might expect additional supporting tools (e.g., listing supported formats or checking ruleset versions). However, the count is not extreme.

Completeness4/5

For the stated goal of validating EU e-invoices, the two tools cover the essential workflow: credential check and document validation. Minor gaps exist, such as no tool to retrieve ruleset metadata or list supported profiles, but the core functionality is present.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-einvoicing-de

    cmendezs
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol (MCP) server for German Electronic Invoicing (ZUGFeRD 2.x / XRechnung 3.x). Provides tools to validate, generate, parse, and convert invoices compliant with EN 16931 and KoSIT.
    50
    2
    Apache 2.0

  • eleata e-invoice MCP server

    hernaninverso
    A
    license
    A
    quality
    B
    maintenance
    Validates EU electronic invoices (Peppol, XRechnung, FatturaPA, etc.) and explains validation error codes, enabling AI coding agents to check invoice validity and get fixes before rejection.
    3
    53
    MIT

  • invoicehub-mcp

    einvoice-dev1
    A
    license
    Not graded
    quality
    C
    maintenance
    EU e-invoice validation, as a developer API. Check whether an electronic invoice conforms to EN 16931 — the European standard behind France, Germany, Belgium, Poland and the 2030 ViDA mandate — with a single REST call. Structured JSON errors mapped to the official BR-* business rules. No enterprise sales call required.
    MIT