ibanforge-mcp

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, 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 not checked yet (the French RIB key, the Italian CIN, the Spanish DC, the German account-number methods): an IBAN with a wrong national key but a correct mod-97 still comes back valid. Only the UK modulus check and the Polish settlement-number check digit are run.

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, and an API key does not raise it.
• 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:

1. Call request_api_key. Read status first — ok means a code was issued.
2. 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.
3. 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.
4. 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. An API key does not increase this remote allowance.

For Claude Code:

claude mcp add --transport http ibanforge https://api.ibanforge.com/mcp

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:

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

For Claude Code:

claude mcp add --transport stdio ibanforge -- npx -y ibanforge-mcp

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:

curl -X POST https://api.ibanforge.com/v1/keys/generate

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), 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

• Website
• API documentation
• OpenAPI 3.1 spec
• x402 discovery
• Issue tracker

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

Apache-2.0