beel-mcp

<p align="center">
  <a href="https://beel.es">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://docs.beel.es/docs-static/beel-logo-dark.svg">
      <img src="https://docs.beel.es/docs-static/beel-logo.svg" alt="BeeL" width="220">
    </picture>
  </a>
</p>

<h1 align="center">BeeL MCP server — VeriFactu e-invoicing for AI agents</h1>

<p align="center">
  Servidor <strong>MCP de facturación electrónica</strong> española con <strong>VeriFactu</strong> (AEAT): crea, emite y rectifica facturas desde <strong>Claude, ChatGPT, Cursor o VS Code</strong>.<br>
  <strong>MCP server for Spanish e-invoicing</strong> with <strong>VeriFactu</strong> compliance — issue, correct and register invoices with AEAT straight from your AI agent.<br>
  <a href="https://beel.es">beel.es</a> · <a href="https://docs.beel.es">API docs</a> · <a href="https://docs.beel.es/mcp">MCP guide</a> · <a href="https://www.npmjs.com/package/@beel_es/mcp">npm</a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@beel_es/mcp"><img src="https://img.shields.io/npm/v/@beel_es/mcp.svg" alt="npm version"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/Model_Context_Protocol-server-224DA9" alt="MCP server"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

---

An [MCP](https://modelcontextprotocol.io) (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 and deprecated operations 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.

```bash
# 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.

```jsonc
// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}
```

```bash
# 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](https://docs.npmjs.com/trusted-publishers), 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](https://registry.modelcontextprotocol.io) 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

- **118 API tools** derived from `openapi/public-api.yaml` — invoices, customers,
  products, recurring invoices, series and tax configuration, NIF validation, companies.
- **4 synthetic tools** the API has no single endpoint for: `beel_docs_search`,
  `beel_docs_get`, `beel_docs_list` over the documentation, and
  `beel_get_setup_status`, which reports per NIF exactly what is missing before it can
  issue and the one next action to take.
- **Guardrail resources** under `beel://guardrails/*` — the fiscal invariants, plus
  `beel://guardrails/errors`, a catalogue of every error code with the action it calls
  for. Their summaries are woven into the description of every tool they constrain.
- **7 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), `onboard-nif`,
  `setup-representation`, `invite-member`, `connect-payments` and `upgrade-integration`.
- **Inline invoice PDF viewer** ([MCP Apps](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp)):
  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](https://docs.beel.es/mcp/tools) (`npm run tools:catalog`).

### What is deliberately not a tool

Binary downloads (PDF preview, bulk ZIP, Excel/CSV export), multipart uploads (CSV/Holded
import, signed-PDF submission), webhook infrastructure, and every `deprecated` operation.
An agent cannot drive them, and each one costs context that a usable tool needs. 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** — `src/guardrails/rules/*.md`, one Markdown file per topic: the invoice
lifecycle, void vs rectify, invoice types, invoice lines, regime keys, series numbering,
NIF validation, the VeriFactu gates, multi-NIF accounts. Each is exposed as an MCP
resource under `beel://guardrails/*` and its one-line summary is appended to the
description of every tool it constrains, 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:

| Check | Code |
|---|---|
| Exactly one pricing field per line | `LINE_UNIT_PRICE_XOR_DECLARED_TOTAL` |
| No discount on a declared total | `LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT` |
| No IRPF withholding on a simplified (F2) invoice | `SIMPLIFICADA_FORBIDS_IRPF` |
| Equivalence surcharge only under regime `18`, and `18` only with one | `SURCHARGE_REQUIRES_REGIME` / `REGIME_REQUIRES_SURCHARGE` |
| Series format can tell its reset periods apart | `SERIES_ANNUAL_REQUIRES_YEAR` / `SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR` |
| Numbering is only seeded in the call that activates the company | `NUMBERING_REQUIRES_ACTIVATION` |
| `SUPLIDO` lines carry their source reference | checked locally |
| Exemption text only under reason `OTRO` | checked locally |
| Correctives go through their own operation, not `type: CORRECTIVE` | checked locally |

**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 (around 357 of them). 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. `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 is a strict subset of what the API refuses: it
can only make failure faster and better explained, never permit something the API would
reject. Rules that depend on server-side state — AEAT census matching, the €3 000 F2
ceiling, whether a series exists — stay advisory on purpose, because guessing at them
locally would reject valid invoices. Set `BEEL_DISABLE_PREFLIGHT=1` to bypass the local
checks entirely.

Hand-curated lists are anchored