BeeL MCP server

Ein MCP (Model Context Protocol) Server, der es einem KI-Agenten ermöglicht, rechtlich konforme spanische elektronische Rechnungen auszustellen – VeriFactu-Registrierung bei der AEAT, F1/F2-Rechnungstypen, R1–R5-Korrekturen, NIF-Validierung gegen das Zensus und die vom Gesetz geforderten Regime-Schlüssel. Verbinden Sie ihn mit Claude, ChatGPT, Cursor oder VS Code und Ihr Agent kann die spanische Rechnungsstellung – facturación electrónica und factura electrónica VeriFactu – Ende-zu-Ende übernehmen, ohne dass Sie einen einzigen API-Aufruf schreiben.

Es ist kein generierter Wrapper um eine API. Drei Dinge machen es für ein Modell nutzbar:

• Tools werden aus dem öffentlichen OpenAPI-Vertrag abgeleitet, sodass das Eingabeschema jedes Tools das tatsächliche Schema der Operation ist – Enums, Positionen, Regime-Schlüssel und alles andere. Die Oberfläche kann nicht von der API abweichen.

• Eine Tool-Aufnahmerichtlinie entscheidet, was einem Agenten tatsächlich zur Verfügung gestellt werden sollte. Binäre Downloads, Multipart-Uploads, Webhook-Infrastruktur und veraltete Operationen werden per Regel ausgeschlossen, nicht von Hand.

• Fiskalische Leitplanken reisen mit den Tools: die Invarianten, die ein generierter Wrapper übersehen würde, sowohl als Dokumentation, die das Modell liest, als auch als Pre-Flight-Prüfungen, die eine nicht konforme Anfrage stoppen, bevor sie zu einem fiskalischen Dokument wird.

Eine Codebasis, zwei Transporte: der gehostete Remote-Server unter https://mcp.beel.es/mcp (Streamable HTTP + OAuth – ein Login pro Benutzer, nichts zu installieren) und ein lokaler stdio-Server, der aus diesem Repository für den Headless-Einsatz gebaut wurde, wo ein API-Schlüssel funktioniert und ein browserbasierter Login nicht.

Schnellstart

Fügen Sie https://mcp.beel.es/mcp als Connector in Claude, ChatGPT, Cursor oder VS Code hinzu und melden Sie sich mit Ihrem BeeL-Konto an. Nichts zu installieren und kein API-Schlüssel zu verwalten: Der Server handelt mit Ihren eigenen Anmeldeinformationen, und der OAuth-Fluss wird aus der URL ermittelt.

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

Das ist die gesamte Einrichtung für die interaktive Nutzung. Lesen Sie weiter nur, wenn Sie den lokalen Server benötigen.

Related MCP server: chile-invoice-mcp

Lokale Ausführung

Verwenden Sie den lokalen Server, wenn OAuth nicht möglich ist: ein geplanter Auftrag, der Rechnungen ausstellt, eine CI-Pipeline oder ein Headless-Prozess, bei dem niemand anwesend ist, um einen Browser-Login abzuschließen. Er authentifiziert sich stattdessen mit einem API-Schlüssel.

Erfordert 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

Schlüssel mit dem Präfix beel_sk_test_ sind sicher zum Experimentieren; beel_sk_live_ erstellt echte fiskalische Dokumente.

Releases werden von CI über npm Trusted Publishing veröffentlicht, sodass sie eine Herkunft haben: npm zeichnet den genauen Commit und Workflow auf, aus dem jeder Build stammt. Überprüfen Sie dies mit npm audit signatures.

Jedes Release wird auch im MCP Registry als es.beel/mcp angekündigt, das beide Transporte auflistet, sodass Clients, die das Registry durchsuchen, den Server finden, ohne darauf hingewiesen zu werden. Der Name wird durch einen DNS-Eintrag auf beel.es authentifiziert, sodass er sagt, dass der Server von uns stammt und nicht nur aus einem Repository.

Ein früherer Eintrag unter io.github.beel-es/beel-mcp (v0.2.2) wurde zurückgezogen, als der Name wechselte. Registry-Namen sind Identitäten und keine Etiketten, daher ist eine Umbenennung ein neuer Eintrag und keine Weiterleitung; beide verweisen auf dasselbe npm-Paket und denselben gehosteten Server.

Was es bietet

• 118 API-Tools, abgeleitet aus openapi/public-api.yaml – Rechnungen, Kunden, Produkte, wiederkehrende Rechnungen, Serien und Steuerkonfiguration, NIF-Validierung, Unternehmen.

• 4 synthetische Tools, für die die API keinen einzelnen Endpunkt hat: beel_docs_search, beel_docs_get, beel_docs_list über die Dokumentation und beel_get_setup_status, das pro NIF genau meldet, was fehlt, bevor es ausstellen kann, und die eine nächste Aktion.

• Leitplanken-Ressourcen unter beel://guardrails/* – die fiskalischen Invarianten, plus beel://guardrails/errors, ein Katalog jedes Fehlercodes mit der Aktion, die er erfordert. Ihre Zusammenfassungen sind in die Beschreibung jedes Tools eingewoben, das sie einschränken.

• 7 Workflow-Prompts, die die sichere Reihenfolge der Operationen für die Abläufe kodieren, bei denen die Reihenfolge das ist, was sie sicher macht: issue-invoice (NIF validieren → F1/F2 wählen → die VeriFactu-Gates prüfen → ausstellen), fix-invoice (stornieren vs. korrigieren), onboard-nif, setup-representation, invite-member, connect-payments und upgrade-integration.

• Inline-Rechnungs-PDF-Viewer (MCP Apps): Das Erzeugen eines Rechnungs-PDFs öffnet es in einem Seitenpanel in Hosts, die dies unterstützen.

Ein generierter Katalog jedes Tools mit den jeweils erforderlichen Berechtigungen befindet sich unter docs.beel.es/mcp/tools (npm run tools:catalog).

Was bewusst kein Tool ist

Binäre Downloads (PDF-Vorschau, Bulk-ZIP, Excel/CSV-Export), Multipart-Uploads (CSV/Holded-Import, signierte PDF-Übermittlung), Webhook-Infrastruktur und jede deprecated-Operation. Ein Agent kann sie nicht steuern, und jede kostet Kontext, den ein nutzbares Tool benötigt. Die Regeln stehen in src/policy/tool-policy.ts.

Die fiskalischen Leitplanken

Die spanische E-Rechnungsstellung hat Invarianten, die ein LLM allein aus dem Schema falsch verstehen wird – eine Rechnung stornieren, die hätte korrigiert werden müssen, R1 auf einer vereinfachten Rechnung verwenden, eine bearbeiten, die die AEAT bereits registriert hat. Der Server adressiert das in drei Schichten, und der Unterschied zwischen ihnen ist wichtig:

1. Beratend – src/guardrails/rules/*.md, eine Markdown-Datei pro Thema: der Rechnungslebenszyklus, Stornierung vs. Korrektur, Rechnungstypen, Rechnungspositionen, Regime-Schlüssel, Seriennummerierung, NIF-Validierung, die VeriFactu-Gates, Multi-NIF-Konten. Jede wird als MCP-Ressource unter beel://guardrails/* bereitgestellt, und ihre einzeilige Zusammenfassung wird an die Beschreibung jedes Tools angehängt, das sie einschränkt, sodass die Einschränkung mit dem Aufruf reist.

2. Erzwungen – src/guardrails/validate.ts, geprüft bevor die Anfrage gesendet wird, sodass eine fehlerhafte Nutzlast nie einen Idempotenzschlüssel verbraucht:

3. Erklärt – Die BeeL-API antwortet bereits gut: Ihre message ist für einen Menschen in der Sprache des Aufrufers geschrieben, error.details trägt die Einzelheiten, und das RFC-7807-type-Feld verlinkt auf eine Dokumentationsseite für genau diesen Code (etwa 357 davon). Der Server leitet all das unverändert weiter und fügt nur die zwei Dinge hinzu, die eine Antwort nicht tragen kann: das Gegenmittel als Tool-Aufruf – die Dokumentation richtet sich an jemanden mit geöffnetem Dashboard („Serie in den Einstellungen erstellen“), ein Agent benötigt beel_set_default_series – und ob ein erneuter Versuch helfen kann, was einen Agenten davon abhält, sich in einer 403-Schleife zu verfangen, die einen Administrator erfordert. src/guardrails/catalog.ts enthält nur Codes, bei denen eines davon zutrifft; alles andere wird durchgereicht, denn eine Paraphrase wäre schlechter als das Original und würde davon abweichen. Die verschachtelten blockers[] von EMISSION_NOT_READY sind der klarste Fall: Sie kommen als nackte Zeichenfolgen ohne Nachricht und ohne Link an, und jede kommt zurück und benennt das Tool, das sie beseitigt.

Die BeeL-API ist die Autorität für alles. Jede erzwungene Regel spiegelt eine Ablehnung wider, die der Vertrag dokumentiert, sodass die Pre-Flight-Prüfung eine strikte Teilmenge dessen ist, was die API ablehnt: Sie kann das Scheitern nur schneller und besser erklärt machen, niemals etwas erlauben, das die API ablehnen würde. Regeln, die vom serverseitigen Zustand abhängen – AEAT-Zensusabgleich, die 3.000-€-F2-Grenze, ob eine Serie existiert – bleiben bewusst beratend, denn lokales Raten würde gültige Rechnungen ablehnen. Setzen Sie BEEL_DISABLE_PREFLIGHT=1, um die lokalen Prüfungen vollständig zu umgehen.

Handkuratierte Listen sind durch Tests verankert: Jeder katalogisierte Code muss weiterhin im Vertrag erscheinen, jede geprüfte operationId muss weiterhin zu einem echten Tool auflösen, und jede Leitplankenreferenz muss auf eine existierende Leitplanke zeigen. Eine API-Umbenennung lässt CI fehlschlagen, anstatt eine fiskalische Prüfung stillschweigend zu deaktivieren.

Konfiguration

Nur lokaler Server

Gemeinsam

Alle Standardwerte stehen in src/shared/defaults.ts; nichts ist doppelt hartkodiert. Variablen für die Remote-Bereitstellung sind in DEPLOY.md dokumentiert.

Der Server startet und listet Tools ganz ohne Zugangsdaten auf – er meldet erst einen Fehler, wenn ein API-Tool tatsächlich aufgerufen wird. POST-Anfragen tragen einen stabilen Idempotency-Key, der aus der Anfrage selbst abgeleitet wird; so kann ein Agent, der „Rechnung erstellen“ erneut versucht, niemals eine zweite Rechnung erzeugen.

Selbsthosting

Der Remote-Server läuft auf Cloudflare Workers. Den KV-Namespace, den OAuth-Client, den BeeL registriert haben muss, und die beteiligten Geheimnisse findest du in DEPLOY.md.

Entwicklung

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock

openapi/public-api.yaml ist eine generierte Kopie des API-Vertrags, und openapi/spec.lock.json erfasst deren Version, Anzahl der Operationen und Hash. CI schlägt fehl, wenn beide nicht übereinstimmen; genau das hält den eingecheckten Vertrag ehrlich. Siehe CONTRIBUTING.md.

Rest von BeeLs Entwickler-Ökosystem

Alles unten Stehende entsteht aus demselben OpenAPI-Vertrag, daher ist das Vokabular – Rechnungstypen, Regimeschlüssel, Serien, VeriFactu-Status – überall identisch, wo du ihm begegnest.

FAQ

Was ist der BeeL-MCP-Server? Ein MCP-Server, der die spanische Veri-E-Rechnung als von KI-Agenten aufrufbare Tools bereitstellt – so können Claude, ChatGPT, Cursor oder VS Code Kunden anlegen, F1/F2-Rechnungen ausstellen, sie bei der AEAT registrieren und R1–R5-Korrekturen in deinem Auftrag senden.

Wie verbinde ich die VeriFactu-Rechnungsstellung mit Claude / ChatGPT / Cursor? Füge https://mcp.beel.es/mcp als Verbindung hinzu und melde dich mit deinem BeeL-Konto an – siehe Schnellstart. Nichts zu installieren und für interaktive Nutzung kein INSERT API-Key.

Ist es wirklich VeriFactu-konform? Ja. Rechnungen werden bei der AEAT unter VeriFactu registriert, Nummerung und Serien folgen der Verordnung, und das fiskal & resholdnavies stoppt nicht konforme Anfragen, bevor sie zu einem steuerlichen Beleg werden.

VeriFactu oder TicketBAI? Dieses Server target VeriFactu, das nationale AEAT-System. TicketBAI (die Regimbas des Baskenlandes) fällt nicht darunter.

Kann ich ihn ohne einen KI-Agenten verwenden? Ja – es ist ein Standard-MCP-Server, funktioniert also mit jedem MCP-fähigen Client; dieselbe Rechnungsschnittserhältlich ist auch als REST API, CLI und n8n node.

Contributing

Fehlerberichte und Pull Requests sind willkommen. Wie das Projekt aufgebaut ist und welche Konventionen verbindlich sind, findest du in CONTRIBUTING.md. Sicherheitsprobleme gehen bitte an security@beel.es statt an ein öffentliches Issue; siehe SECURITY.md.

Lizenz

MIT © BeeL.