Zum Inhalt springen
IBANforge

MCP-Integration

IBANforge liefert einen offiziellen MCP-Server für KI-Agenten: ibanforge-mcp auf npm, plus einen gehosteten Endpoint ganz ohne Installation. Claude, Cursor oder jeder MCP-kompatible Client kann IBANs validieren, BICs auflösen, Schweizer Clearing-Nummern prüfen und eine Compliance-Vorprüfung als Tool-Aufrufe ausführen.

Was ist MCP?

Das Model Context Protocol ist ein offener Standard, der KI-Assistenten die Nutzung externer Tools erlaubt. Statt den Nutzer API-Ergebnisse kopieren zu lassen, ruft der Agent das Tool direkt auf und erhält strukturierte Daten zurück.

Option 1 — das npm-Paket (stdio)

Claude Desktop — IBANforge in die Konfigurationsdatei eintragen:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["-y", "ibanforge-mcp"],
      "env": { "IBANFORGE_API_KEY": "ifk_ihr_schluessel" }
    }
  }
}

Claude Code — ein einziger Befehl:

claude mcp add ibanforge -e IBANFORGE_API_KEY=ifk_ihr_schluessel -- npx -y ibanforge-mcp

Der Schlüssel ist optional und kostenlos — 25 Anfragen/Monat ohne E-Mail. Generieren Sie einen per POST ohne Body und senden Sie Authorization: Bearer ifk_.... Mit einem Code per E-Mail beanspruchen Sie denselben Schlüssel für 200/Monat, ohne Kreditkarte.

Nach dem Speichern den Client neu starten. Das npm-Paket bietet 13 Tools, der entfernte HTTP-Server 11. Die zwei Datei-Audit-Tools sind nur im npm-Paket verfügbar. Siehe Katalog nach Transport.

Option 2 — der gehostete Endpoint (nichts zu installieren)

https://api.ibanforge.com/mcp

Streamable-HTTP-Transport, 10 kostenlose Tool-Aufrufe pro IP und Tag, ganz ohne Schlüssel: der schnellste Weg für einen Agenten, die Daten zu prüfen, bevor Sie sich festlegen. Für dauerhafte Nutzung das npm-Paket mit dem kostenlosen Schlüssel betreiben.

Im offiziellen MCP-Registry ist der Server als io.github.cammac-creator/ibanforge gelistet.

Verfügbare Tools

validate_iban

Validiert eine einzelne IBAN: Struktur und Prüfziffer, ausgebende Bank (BIC), Bankcode-Prüfung gegen das Nationalregister, EMI/vIBAN-Klassifikation, SEPA/VoP-Erreichbarkeit und Risikoindikatoren — dieselben Daten wie POST /v1/iban/validate.

{ "iban": "CH1000230000000012345" }

batch_validate_iban

Bis zu 100 IBANs in einem Aufruf, jedes Ergebnis strukturgleich zu validate_iban — wie POST /v1/iban/batch.

{ "ibans": ["CH1000230000000012345", "DE89370400440532013000"] }

lookup_bic

Institutsdetails zu einem BIC/SWIFT-Code: Name, Land, Stadt, Filiale, LEI wo vorhanden — wie GET /v1/bic/:code.

{ "code": "UBSWCHZH80A" }

lookup_ch_clearing

Schweizer BC-Nummer / IID nachschlagen: Institut, Typ, Ort, SIC/euroSIC-Teilnahme und QR-IID-Zuteilung — wie GET /v1/ch/clearing/:iid.

{ "iid": "230" }

check_compliance

Vollständige Vorprüfung in einem Aufruf: Sanktionsprüfung auf dem aufgelösten Bank-BIC, FATF-Status, SEPA-Instant-Erreichbarkeit, VoP-Teilnahme und ein zusammengesetzter Risikoscore von 0 bis 100 — wie POST /v1/iban/compliance.

{ "iban": "CH1000230000000012345" }

validate_payment_reference

Validiert eine strukturierte Zahlungsreferenz — RF/ISO 11649 (SCOR), Schweizer QR-Referenz (QRR), belgische OGM/VCS, finnische viitenumero — und entscheidet, sobald eine iban mitgegeben wird, ob beide zusammen reisen dürfen. Kostenlos; derselbe Vertrag wie GET /v1/reference/validate, ergänzt um das Zuordnungsurteil.

valid und pairing sind unabhängig: Eine Referenz kann arithmetisch gültig und auf diesem Konto dennoch unzulässig sein. Die norwegische KID und die schwedische OCR antworten mit valid: null — ihre Regeln werden pro Gläubigerkonto von der Bank des Begünstigten konfiguriert — und dürfen nie als „ungültig" weitergegeben werden.

{ "reference": "210000000003139471430009017", "iban": "CH4431999123000889012" }

check_postal_address

Prüft eine strukturierte ISO-20022-Postadresse gegen die veröffentlichten Regeln eines Zahlungsrails — sps (Swiss Payment Standards), hvps_plus (T2) oder fedwire — Regel für Regel, wobei jeder Befund das Dokument und sein Gültigkeitsdatum nennt. Kostenlos; gleicher Vertrag wie POST /v1/address/check. Ein cbpr+-Schema fehlt mit Absicht: diese Richtlinie ist für automatisierte Leser unerreichbar, und das Feld note der Antwort sagt das bei jedem Aufruf.

{ "scheme": "sps", "address": { "strt_nm": "Bahnhofstrasse", "bldg_nb": "45", "pst_cd": "8001", "twn_nm": "Zurich", "ctry": "CH" } }

check_swiss_qr_bill

Prüft die Nutzdaten einer Swiss-QR-Rechnung, den Text im QR-Code (er beginnt mit SPC), Regel für Regel: Kopfzeilen, Kreditoren-IBAN und QR-IBAN-Bereich, Prüfziffern der Referenzen QRR / SCOR / NON und ihre Paarung mit der IBAN, Betrag, Währung, und ob die Adressen von Kreditor und Debitor strukturiert (Typ S) oder noch kombiniert (Typ K) sind. Der Standard hat Typ K am 21. November 2025 entfernt, und die Banken verarbeiten darauf beruhende Zahlungen ab dem 14. November 2026 nicht mehr; eine kombinierte Adresse kommt mit proposed_structured zurück, den aus den kombinierten Zeilen abgeleiteten S-Feldern. Kostenlos, geroutet auf POST /v1/ch/qr-bill/check.

{ "payload": "SPC\n0200\n1\nCH4431999123000889012\nS\nRobert Schneider AG\nRue du Lac\n1268\n2501\nBiel\nCH\n\n\n\n\n\n\n\n1949.75\nCHF\nS\nPia Rutschmann\nMarktgasse\n28\n9400\nRorschach\nCH\nQRR\n210000000003139471430009017\nOrder 15.06.2026\nEPD" }

audit_creditor_file

Prüft eine gesamte Kreditoren-/Lieferantendatei (CSV oder XLSX) zeilenweise: IBAN-Struktur und Prüfziffer, Bankcode gegen das Nationalregister, Bankname und BIC, SEPA-Erreichbarkeit und Emittententyp, plus Prüfungen, die ein einzelner IBAN-Aufruf nicht leisten kann, weil sie die ganze Datei brauchen — doppelte IBANs, der von der Datei mitgeführte BIC gegen den vom Register abgeleiteten BIC, Adressland gegen IBAN-Land, und die Konformität strukturierter Schweizer Adressen vor der Frist am 14. November 2026. Liefert nur eine kostenlose Vorschau (maskierte IBANs, Summenzahlen, bis zu 20 Zeilen) — der vollständige annotierte .xlsx-Bericht ist eine kostenpflichtige Leistung (149 $ bis 5'000 Zeilen, 349 $ bis 20'000), beglichen über eine einmalige Stripe-Checkout-Session, nie automatisch bezahlt. Mit checkout: true wird zusätzlich die Checkout-URL zurückgegeben, die ein Mensch öffnet. Die Datei base64-kodiert als file_base64 senden; Dateien über 5 MB werden lokal abgelehnt, vor jedem Netzwerkaufruf: darüber sprengt die Base64-Nutzlast den stdio-Kanal, und der Agent verliert seine Verbindung, statt einen Fehler zu erhalten. Die HTTP-Route nimmt bis zu 10 MB — für eine grosse Datei diesen Weg nehmen.

{ "file_base64": "Tm9tO0lCQU4KU29jaWV0ZSBBbHBoYTtDSDEwMDAyMzAwMDAwMDAwMTIzNDUK", "filename": "kreditoren.csv", "lang": "de" }

audit_status

Prüft den Status eines von audit_creditor_file erstellten Audit-Jobs: ob bezahlt wurde, und den Download-Link, sobald bezahlt ist. Die session_id aus der Erfolgs-Weiterleitung der Checkout-URL übergeben, um eine gerade abgeschlossene Zahlung sofort zu bestätigen, ohne auf den Webhook zu warten. Kostenlos.

{ "job": "42aefe9921c83ff967591a89a013598aea91", "session_id": "cs_test_..." }

audit_creditor_file und audit_status gibt es vorerst nur im npm-Paket (Option 1) — noch nicht auf dem gehosteten HTTP-Endpoint (Option 2).

send_feedback

Ein falsches Ergebnis, veraltete oder fehlende Daten oder alles, was Sie an der Nutzung oder an der BEZAHLUNG des Dienstes hindert, direkt an die Betreiber melden. Kostenlos, und das Tool antwortet auch dann noch, wenn das kostenlose Tageskontingent aufgebraucht ist: den Beschwerdekasten mit genau der Grenze zu deckeln, die die Beschwerde auslöst, würde die Meldungen zum Schweigen bringen, für die er da ist. Ein Mensch liest jede Meldung; ein nachgewiesener Datenfehler bei einem bezahlten x402-Aufruf wird on-chain erstattet. error_type und notes sind Pflicht, der Rest ist optional.

{ "error_type": "wrong_bic", "notes": "BIC verweist auf eine 2024 fusionierte Bank", "endpoint": "/v1/iban/validate", "contact": "acme@example.com" }

request_api_key

Einen Schlüssel ohne E-Mail anfordern: Das Tool liefert einen Link, den eine Person im Browser öffnet und genehmigt. Auf beiden Transporten verfügbar.

poll_api_key

Den genehmigten Schlüssel mit dem device_code von request_api_key abholen. Er wird nur einmal ausgegeben: bewahren Sie ihn auf. Auf beiden Transporten verfügbar.

Ergebnisse, die sagen, was als Nächstes zu tun ist

Jedes Validierungsergebnis trägt ein geordnetes Feld next_steps: Was eine Zahlung blockiert, kommt zuerst, was sie nur anreichert, danach. Jeder Eintrag hat einen stabilen code zum Verzweigen, einen do-Satz, den der Agent weitergeben kann, und ein because, das das Antwortfeld nennt, aus dem der Rat entstand — der Rat ist prüfbar statt geglaubt. bank_code_not_allocated heißt Stopp; verify_payee_name heißt weitermachen und eine Empfängernamen-Prüfung entscheiden lassen.

Beispielkonversation mit einem Agenten

Sie: Ist diese IBAN gültig? CH10 0023 0000 0000 1234 5

Claude: Ich validiere die IBAN. [ruft validate_iban auf]

Ja, die IBAN ist gültig — und der Bankcode ist im SIX-Register bestätigt: UBS Switzerland AG in Zürich, BIC UBSWCHZH, BC-Nummer 00230, SIC-Teilnehmer mit CHF-Echtzeitzahlungen.

Sie: Kannst du diese 3 IBANs aus der Lieferantenrechnung prüfen?

Claude: Ich validiere alle drei auf einmal. [ruft batch_validate_iban auf]

2 von 3 sind gültig. Die dritte (FR76...) hat einen Prüfziffernfehler — vermutlich wurden zwei Ziffern vertauscht.

Funktioniert gut mit

PayQR — npx -y @czagents/payqr, gehostetes MCP https://payqr.cz-agents.dev/mcp, Registry dev.cz-agents/payqr. Erzeugt und prüft selbst einen europäischen Zahlungs-QR aus einer IBAN und den Zahlungsdetails: SPAYD für CZ/SK-Konten, EPC/GiroCode (nur EUR) für andere SEPA-Konten; EPC verlangt recipient_name. PayQR validiert die IBAN-Prüfziffer, verifiziert aber weder Kontoinhaberschaft noch Empfängernamen und erzeugt keine nativen Schweizer QR-Rechnungen — Registerprüfung, VoP-Bereitschaft und Risikoindikatoren sind genau das, was IBANforge obendrauf liefert.

Unterstützte Clients

  • Claude Desktop und Claude Code — natives MCP
  • Cursor und Continue.dev — über deren MCP-Konfiguration
  • n8n — besser den dedizierten Community-Node nutzen
  • Eigene Agenten — jede App mit dem MCP SDK

Hinweise

  • Das npm-Paket ist ein schlanker Client für api.ibanforge.com: Die Daten leben serverseitig, nichts herunterzuladen, und Ergebnisse spiegeln stets die letzte Registeraktualisierung.
  • Ergebnisse werden als Text und MCP-structuredContent zurückgegeben. Zwei Audit-Tools sind nur im npm-Paket verfügbar; alle anderen sind auch remote verfügbar.
  • Releases erscheinen auf npm und werden ins MCP-Registry gespiegelt.

Siehe auch: Rezepte · Was „verified" bedeutet · Datenquellen