BeeL

BeeL MCP server — VeriFactu e-invoicing for AI agents

Servidor MCP de facturación electrónica española con VeriFactu (AEAT): crea, emite y rectifica facturas desde Claude, ChatGPT, Cursor o VS Code .

MCP server for Spanish e-invoicing with VeriFactu compliance — issue, correct and register invoices with AEAT straight from your AI agent.

beel.es · API docs · MCP guide · npm

An MCP (Model Context Protocol) server that lets an AI agent issue legally compliant Spanish electronic invoices — VeriFactu registration with AEAT, F1/F2 invoice types, R1–R5 correctives, NIF validation against the census, and the regime keys the regulation requires. Connect it to Claude, ChatGPT, Cursor or VS Code and your agent can handle Spanish invoicing — *facturación electrónica* and *factura electrónica VeriFactu* — end to end, without you writing a single API call.

It is not a generated wrapper around an API. Three things make it usable by a model:

• Tools are derived from the public OpenAPI contract, so each tool's input schema is the operation's real schema — enums, line items, regime keys and all. The surface cannot drift from the API.
• A tool-inclusion policy decides what an agent should actually be given. Binary downloads, multipart uploads, webhook plumbing, operations only a browser session can authenticate, and deprecated ones are excluded by rule, not by hand.
• Fiscal guardrails travel with the tools: the invariants a generated wrapper would miss, both as documentation the model reads and as pre-flight checks that stop a non-compliant request before it becomes a fiscal document.

One codebase, two transports: the hosted remote server at https://mcp.beel.es/mcp (Streamable HTTP + OAuth — one login per user, nothing to install), and a local stdio server built from this repository for headless use, where an API key works and a browser-based login does not.

Quick start

Add `https://mcp.beel.es/mcp` as a connector in Claude, ChatGPT, Cursor or VS Code and log in with your BeeL account. Nothing to install and no API key to handle: the server acts with your own credentials, and the OAuth flow is discovered from the URL.

# Claude Code

claude mcp add --transport http beel https://mcp.beel.es/mcp

That is the whole setup for interactive use. Read on only if you need the local server.

Running it locally

Use the local server when OAuth cannot: a scheduled job that issues invoices, a CI pipeline, or any headless process where no one is present to complete a browser login. It authenticates with an API key instead.

Requires Node ≥ 20.

// Claude Desktop / Claude Code MCP config

{ "mcpServers": { "beel": { "command": "npx", "args": ["-y", "@beel_es/mcp"], "env": { "BEEL_API_KEY": "beel_sk_test_xxx" } } } }

# Claude Code

claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

Keys prefixed beel_sk_test_ are safe to experiment with; beel_sk_live_ issues real fiscal documents.

Releases are published from CI through npm trusted publishing, so they carry provenance: npm records the exact commit and workflow each build came from. Verify it with npm audit signatures.

Each release is also announced to the MCP Registry as `es.beel/mcp`, listing both transports, so clients that browse the registry find the server without being pointed at it. The name is authenticated by a DNS record on beel.es, so it says the server comes from us and not merely from some repository.

An earlier listing under io.github.beel-es/beel-mcp (v0.2.2) was retired when the name moved. Registry names are identities rather than labels, so a rename is a new entry rather than a redirect; both point at the same npm package and the same hosted server.

What it provides

• 129 API tools derived from openapi/public-api.yaml — invoices, customers, products, recurring invoices, series and tax configuration, NIF validation, companies.
• 7 synthetic tools the API has no single endpoint for: beel_docs_search, beel_docs_get, beel_docs_list over the documentation (the docs site's search endpoint and one page's Markdown at a time, or some of its sections in one call: a long page answers with its outline); beel_rules_list and beel_rules_get over the fiscal rules catalogue (by id, several ids at once, domain, keyword or error code); beel_schema_get, the fields of request and response schemas as compact TypeScript-like declarations from the bundled contract (by schema name, or by tool name for its query, body and return type); and beel_get_setup_status, which reports per NIF exactly what is missing before it can issue, the one next action to take, and the ids an integration starts from (company, default series per document type, VeriFactu status and tax defaults).
• Guardrail resources under beel://guardrails/* — the fiscal rules, one resource per domain, the API usage guides, and beel://guardrails/errors, a catalogue of every error code with the action it calls for. The domains and guides that apply are named in the description of every tool they constrain.
• 9 workflow prompts encoding the safe order of operations for the flows where the order is what makes them safe: issue-invoice (validate NIF → choose F1/F2 → check the VeriFactu gates → issue), fix-invoice (void vs correct), fix-rejection (act on an AEAT rejection by code family), onboard-nif, go-live-checklist, setup-representation, invite-member, connect-payments and upgrade-integration.
• Inline invoice PDF viewer (MCP Apps): generating an invoice PDF opens it in a side panel in hosts that support it.

A generated catalogue of every tool, with the scopes each requires, lives at docs.beel.es/mcp/tools (npm run tools:catalog).

What is deliberately not a tool

Binary downloads (PDF preview, bulk ZIP, Excel/CSV export), binary uploads (Holded import, signed-PDF submission, logo), webhook infrastructure, operations that only a browser session can authenticate, and every deprecated operation. An agent cannot drive them, and each one costs context that a usable tool needs. The CSV imports of managed accounts and customers are tools: the agent passes the CSV as text and the server sends the file. The rules are in src/policy/tool-policy.ts.

The fiscal guardrails

Spanish e-invoicing has invariants an LLM will get wrong from the schema alone — voiding an invoice that should have been corrected, using R1 on a simplified invoice, editing one AEAT has already registered. The server addresses that in three layers, and the difference between them matters:

1. Advisory — two sources, kept apart on purpose:

• The fiscal rules are the catalogue the documentation site publishes at docs.beel.es/api/rules.json: each rule has an id (COR-002), a statement, why it exists, its legal basis, the error codes that enforce it and examples. The server reads it at runtime (cached, like the other docs files) and serves it through beel_rules_list / beel_rules_get and one resource per domain (beel://guardrails/corrective, …). Nothing fiscal is re-typed here. A snapshot of the catalogue ships in the package as a fallback for when the docs host is unreachable; npm run sync:rules is its only writer, and a test fails if it was edited by hand. The former beel://guardrails/cancel-vs-rectify, invoice-types and regime-keys URIs still resolve, to the domains that replaced them.
• The API usage guides — src/guardrails/rules/*.md — cover what is not a fiscal rule but still trips an agent: how a line states its price, how a series is configured, which company an operation acts on, how to read NIF validation and issuing readiness, and which tool performs each invoice operation. They link to rule ids rather than restating them.

The domains and guides that apply are named in the description of every tool they constrain, so the constraint travels with the call.

2. Enforced — src/guardrails/validate.ts, checked before the request is sent, so a bad payload never even consumes an idempotency key:

3. Explained — the BeeL API already answers well: its message is written for a human in the caller's language, error.details carries the specifics, and the RFC 7807 type field links to a documentation page for that exact code. The server relays all of that untouched, and adds only the two things a response cannot carry: the remedy as a tool call — the docs address someone with the dashboard open ("create a series in settings"), an agent needs beel_set_default_series — and whether retrying can possibly help, which is what stops an agent looping on a 403 that needs an administrator. When the code is one a published rule cites, the error also names that rule (id, title, link). src/guardrails/catalog.ts holds only codes where one of those applies; anything else passes through, because a paraphrase would be worse than the original and would drift from it. The nested blockers[] of EMISSION_NOT_READY are the clearest case: they arrive as bare strings with no message and no link, and each comes back out naming the tool that clears it.

The BeeL API is the authority on all of it. Every enforced rule mirrors a rejection the contract documents, so the pre-flight