ibanforge-mcp
[npm]
[License]
Official Model Context Protocol (MCP) server for IBANforge.
Check the bank behind an IBAN before you pay: validation in 89 countries, a bank-code verdict from the national register (DE, AT, BE, SK, CZ, BG, CH, LI at this release; the live list is in llms.txt), the bank and BIC with their source, the SEPA, SEPA Instant and VoP readiness of the bank, and bank-level sanctions (OFAC, EU, UN).
Not a name check (VoP, BAV, CoP), not proof that an account exists or is open, not a sanctions screening of the payee (bank and country only), not a licensed copy of the SWIFT BIC directory. The national check digits inside the BBAN are checked for France and Monaco (RIB key), Belgium, Italy and San Marino (CIN), Spain (DC), Germany (the account-number check digit, by the Bundesbank method of each bank code) and the United Kingdom (modulus check): a wrong key shows in checks.national_check_digits and never turns valid to false. The Polish settlement-number check digit is checked with the bank code. The national keys of the other countries are not checked yet.
For business software and AI agents alike: an API key that needs no e-mail, prepaid packs by card, and x402 micropayments on the HTTP API.
Free access
This README gives no figures on purpose: a published package stays as it is until the next release, while the allowances of the service can change. The figures in force are served live at rate-limits.yml and by GET /v1.
- Remote MCP, nothing to install:
https://api.ibanforge.com/mcp answers full tool calls without a key or a wallet, within its own allowance per source address (mcp_anonymous in rate-limits.yml), a batch counting one per IBAN. It is separate from the REST trial below. With an API key in the Authorization: Bearer header, its calls count against that key exactly as on the REST API.
- This package, before you have a key:
validate_iban goes through the REST API's keyless trial (rest_anonymous_trial), counted per source address; the trial block of each answer says how many calls are left and when the count resets. The other paid tools need a key, prepaid credits or x402.
- A key that needs no e-mail and no card:
POST https://api.ibanforge.com/v1/keys/generate with an empty body returns an ifk_ key with its own allowance on every endpoint (anonymous_key). Claimed at POST /v1/keys/claim with a code mailed to an address given for this, the same key gets a larger allowance (free_tier; see Keep using the same key).
Tools
The USDC prices are those of x402 payments on the HTTP API, the only way a batch costs less per IBAN than single validations. On a key or prepaid credits, each paid call uses one request or one credit, and each IBAN of a batch uses one.
Get a durable key from inside your MCP client
No e-mail, no account, no form. Four steps, about fifteen seconds of human time:
- Call
request_api_key. Read status first — ok means a code was issued.
- Show your human the
display_to_human block verbatim: it carries the short code
and the link. Do not open the link yourself, and never invent an address.
- Your human opens the page, checks the code matches, and clicks. The page gives a key
with no address at all; they may add one there to raise the allowance.
- Call
poll_api_key (no argument needed). On approved it carries the key once,
plus a ready-made config_line to paste. Save it as IBANFORGE_API_KEY and reconnect.
Both tools are free and keep working after the free allowance is spent — that is the point
of them.
Connect and get a first result
Remote MCP: no installation or key
Use the Streamable HTTP URL https://api.ibanforge.com/mcp in a compatible MCP client.
This remote service has its own allowance per source address (see Free access);
each IBAN in a batch counts as one unit. With a key sent as Authorization: Bearer ifk_...
(or X-API-Key), tool calls count against that key exactly as on the REST API, instead of
this allowance. A key in the URL is not read.
For Claude Code:
In Claude and Claude Desktop, add the key under Request headers when you create the custom
connector, where the dialog shows that section: Anthropic keeps it in beta and does not open it to
every account. An existing connector is removed and added again to take a key. ChatGPT sends no
key to a connector: there, the remote service stays on its keyless allowance.
Ask: “Validate DE89370400440532013000, identify the bank, and explain what the result
can and cannot prove.” Read valid, bank_code_check and the provenance of any BIC.
A valid checksum does not prove that an account exists or belongs to a named person.
Installed MCP: REST access with an optional reusable key
For Claude Desktop, add this to its MCP configuration; for Cursor, use .cursor/mcp.json:
For Claude Code:
This configuration intentionally works without a placeholder key. The installed package
calls the REST API: without a key, validate_iban uses its keyless trial, separate
from remote MCP. Always read the returned limits; individual free utilities have their
own protections. After the trial, single-IBAN validation may return format only, marked
_degraded: true and _scope: "format_only". It contains no bank, SEPA or compliance verdict.
A rejected batch returns an error; it is not expanded into individual free requests.
Keep using the same key
Create a key without supplying an address:
Store the returned api_key securely and add it as IBANFORGE_API_KEY in the MCP server's
env object, then reconnect the client. Do not paste a placeholder key and do not mint a
new key for every conversation. The key starts at the allowance given in
Free access; read monthly_limit, since a temporary protection can reduce it.
It provides a stable identity, a dedicated quota and GET /v1/keys/usage.
Once used, that same key can be claimed at POST /v1/keys/claim, with
Authorization: Bearer ifk_…, never a key in the body. A six-digit code sent to an address
explicitly supplied for this purpose raises the key's allowance, renewed with each new period. An
x402 payment made on the key raises it once, without renewal. The figures are those of free_tier in
rate-limits.yml. Do not infer an
address or initiate payment without authorization. Prepaid credits also work with the
configured key: one credit per call, and one per IBAN in a batch.
This package has no wallet and does not sign or automatically pay x402 requests.
It returns the API's payment requirements. To pay per call, use an x402-capable HTTP client
following the payment guide.
Recover without guessing
isError: true: no successful tool result. Inspect error, status, cause and _hint.
402: follow the existing key's cause or configure an available key; do not create keys to bypass limits.
429: wait for retry_after when present. The client forwards the HTTP Retry-After value.
request_timeout / transport_error: no complete response was received. This is not a bank verdict.
_degraded: true: only format was checked. Never use it as evidence of bank or SEPA reachability.
Requests time out after 30 seconds, including reading the response body. There is no automatic
retry: an interrupted upload or other POST may already have been processed.
Examples
After adding the server, ask your AI agent:
- "Validate the IBAN DE89 3704 0044 0532 0130 00 and tell me which bank holds its code"
- "Is the bank code of CH93 0076 2011 6238 5295 7 allocated?" (the IBAN passes mod-97; the
SIX register allocates its bank code to nobody, so
bank_code_check.reason is not_allocated)
- "Look up BIC UBSWCHZH80A"
- "Look up Swiss BC-Nummer 230"
- "Run a compliance check on IBAN GB29 NWBK 6016 1331 9268 19"
- "Validate these 5 IBANs in batch: …"
Configuration
Data sources
- Bank-code verdict: the national registers of Germany (Bundesbank), Austria (OeNB), Belgium (NBB), Slovakia (NBS), the Czech Republic (ČNB), Bulgaria (BNB) and Switzerland and Liechtenstein (SIX BankMaster) at this release, where a code the register does not hold is
not_allocated; elsewhere a partial register or a composite map, where a miss is not a refusal. The live list is in llms.txt.
- 121k+ BIC entries (entries, not institutions). GLEIF and the national registers are refreshed monthly; the SwiftCodes rows are a public copy of the SWIFT directory frozen in January 2018, re-imported without changing, and still about two thirds of the directory. Exact live counts at api.ibanforge.com/llms.txt. Sources:
- PeterNotenboom/SwiftCodes (MIT-licensed public copy of the SWIFT directory, data frozen in January 2018)
- GLEIF BIC-LEI mapping (the only rows with LEI codes, 39k+)
- EBA Clearing STEP2 SCT (official SEPA Reachable PSPs directory)
- Deutsche Bundesbank BLZ (official quarterly file)
- NBP EWIB (official Polish bank registry)
- SIX Group BankMaster (Swiss BICs)
- 1,100+ BC-Nummern from the official SIX BankMaster CSV
- EMI / vIBAN classification from a curated set of non-bank issuers (EMIs, payment institutions, digital banks) and, for Spanish bank codes, the EBA PSD2 register; the live count is served at llms.txt
- VoP readiness from the EPC Verification of Payee scheme register (
vop.csv), refreshed weekly with the other compliance lists
- Sanctions from the OFAC, EU and UN lists, matched on the payee's bank (BIC8) and country, never on the payee's name
Links
Legal
Calls made through this server hit the hosted API and are governed by the
Terms of Service (privacy,
DPA). Validation confirms IBAN structure
and registry data — it does not confirm that an account exists or belongs to
anyone; verify the payee by name before sending funds.
License
MIT