MCP server for ibanchecker.cash that adds five IBAN and BIC tools to AI assistants like Claude.
Validate a single IBAN: country, length, BBAN structure, MOD-97 check digits, and bank details when available.
Bulk validate up to 100 IBANs in one call.
Extract and validate every IBAN from free-form text such as emails, invoices, or spreadsheets.
Get IBAN format specifications for supported countries; works without an API key, rate-limited.
Look up bank details by BIC/SWIFT code.
Runs hosted remotely or locally over stdio; validation is in-memory and no IBAN data is stored.
MCP (Model Context Protocol) server for ibanchecker.cash. Gives AI assistants like Claude five finance tools backed by the ibanchecker.cash validation engine:
Tool | What it does |
| Validate a single IBAN: country, length, national BBAN structure, MOD-97 check digits, and bank details when available |
| Validate up to 100 IBANs in one call |
| Find and validate every IBAN inside a block of text (emails, invoices, spreadsheets) |
| IBAN format specification for any of 92 supported countries |
| Look up a bank by BIC/SWIFT code |
No IBAN data is logged or stored; validation runs in memory on Cloudflare's edge. See the security page for details.
The easiest path is the hosted endpoint. Nothing to install or deploy. Every tool except get_iban_format needs an API key (see API key).
https://mcp.ibanchecker.cash/mcpClaude Code
claude mcp add --transport http ibanchecker https://mcp.ibanchecker.cash/mcp --header "Authorization: Bearer YOUR_API_KEY"Claude Desktop (claude_desktop_config.json), via the mcp-remote bridge:
{
"mcpServers": {
"ibanchecker": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.ibanchecker.cash/mcp", "--header", "Authorization:${AUTH_HEADER}"],
"env": {
"AUTH_HEADER": "Bearer your-api-key-here"
}
}
}
}Related MCP server: mcp-europe-business
Run the server locally over stdio (requires Node 18+):
{
"mcpServers": {
"ibanchecker": {
"command": "npx",
"args": ["-y", "@ibanchecker/mcp"],
"env": {
"IBANCHECKER_API_KEY": "your-api-key-here"
}
}
}
}Calling validate_iban with DE89370400440532013000 returns:
{
"valid": true,
"iban": "DE89370400440532013000",
"formatted": "DE89 3704 0044 0532 0130 00",
"country_name": "Germany",
"bank_name": "Commerzbank AG Cologne",
"bic": "COBADEFFXXX",
"bank_code": "37040044",
"account_number": "0532013000",
"sepa": true
}When the API returns an error (for example a 429 rate limit, a 401 missing or bad key, or a 403 tool outside the key's plan), the tool result is flagged with isError: true and a human-readable message, so the assistant can react rather than crash.
Every tool except get_iban_format needs an API key, and what a key can call follows its plan:
Tool | Free key | Free key with a verified account | Basic / Starter | Growth / Enterprise |
| yes | yes | yes | yes |
| no | up to 10 IBANs a call | up to 100 | up to 100 |
| no | yes | yes | yes |
| no | up to 5,000 characters a call | trial with a verified account | up to 50,000 |
| yes | yes | yes | yes |
get_iban_format also works without a key, up to 100 requests an hour per IP. A free key covers 100 requests a month and arrives by email in seconds: get one at ibanchecker.cash/api-docs. A free account on the same address, at ibanchecker.cash/dashboard, opens the trials. Bulk validation and extraction count one request per IBAN. See ibanchecker.cash/pricing for higher volumes. Pass the key as:
IBANCHECKER_API_KEY env var (stdio mode), or
Authorization: Bearer <key> / x-api-key header (remote mode).
.
├── bin/stdio.mjs # npm CLI entry (published as `ibanchecker-mcp`)
├── shared/tools.mjs # the 5 tool definitions, shared by both transports
└── worker/ # Cloudflare Worker (the hosted remote server)
├── src/index.ts
└── wrangler.tomlBoth the stdio CLI and the Worker register the exact same tools from shared/tools.mjs, so there is a single source of truth.
The remote server is a Cloudflare Worker built on the Agents SDK. Deploy your own:
cd worker
npm install
npx wrangler deployRemove the routes block in worker/wrangler.toml (or point it at your own domain) and optionally set a server-wide key with npx wrangler secret put IBANCHECKER_API_KEY.
MIT. See LICENSE.
Scan a free-form block of text and pull out every candidate IBAN, then validate each one.
Useful for unstructured sources such as emails, invoices, PDFs pasted as text, or chat messages where IBANs appear inline and may be split by spaces or surrounded by other words. Returns JSON with count, valid_count, invalid_count and results, one validate_iban-shaped entry per IBAN found; text containing no IBAN returns an empty list rather than an error.
Use this as the first step when the account number is buried in prose; pass the extracted IBANs to validate_bulk_ibans only if you need to re-check them separately. Input text is processed in memory and not stored. Requires an API key on the Growth plan or above; a free key whose address has a verified ibanchecker.cash account can try it with up to 5,000 characters per call. Each IBAN found counts as one request.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Arbitrary text to scan for IBANs, e.g. the body of an email or invoice. IBANs may be split across spaces or embedded in sentences. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: in-memory processing with no storage, API key plan requirements (Growth+), a 5,000-character free-tier limit, request accounting (one per IBAN), and the important behavioral fact that text with no IBANs returns an empty list rather than an error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, then use cases, then return shape, then operational constraints. Every sentence carries distinct, actionable information with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the return fields (count, valid_count, invalid_count, results) and the entry shape. Combined with the plan/auth notes and error-free empty-result behavior, an agent has everything needed to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is only one parameter, so the schema already documents it (baseline 3). The description adds genuine meaning about the parameter's expected content and quirks — emails, invoices, pasted PDFs, chat messages, and IBANs split by spaces — which helps an agent prepare input correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb+resource: 'Scan a free-form block of text and pull out every candidate IBAN, then validate each one.' It clearly distinguishes extraction-and-validate from siblings validate_iban and validate_bulk_ibans, which take known IBANs rather than discovering them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames itself as 'the first step when the account number is buried in prose' and routes follow-up work: 'pass the extracted IBANs to validate_bulk_ibans only if you need to re-check them separately.' Names both the when and the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the IBAN format specification for a country, covering 92 supported IBAN-using countries.
Returns JSON describing the country's total IBAN length, the BBAN layout (bank code, branch code, and account number positions and lengths), an example IBAN, and the SEPA-membership flag. Use this to understand or display how a country's IBAN is structured, to build input masks, or to explain a validation failure, not to validate a specific number (use validate_iban for that). An unsupported or unknown country code returns an error result describing the problem. Works without an API key, up to 100 requests an hour per IP.
| Name | Required | Description | Default |
|---|---|---|---|
| country_code | Yes | Two-letter ISO 3166-1 alpha-2 country code, case-insensitive (e.g. 'DE' for Germany, 'GB' for the United Kingdom, 'FR' for France). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that: no API key required, a 100-requests/hour-per-IP rate limit, and explicit error behavior for unsupported country codes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then usage and constraints, with no filler sentences. It is somewhat long because it enumerates the returned fields, but each clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description enumerates what the JSON contains (total length, BBAN layout, example IBAN, SEPA flag). Combined with rate-limit and error-behavior disclosure, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single country_code parameter, so the schema already documents the ISO 3166-1 alpha-2 format, case-insensitivity and examples. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the IBAN format specification for a country') and immediately scopes it with the supported-country count. It clearly distinguishes itself from validate_iban by naming the sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use cases ('understand or display how a country's IBAN is structured, to build input masks, or to explain a validation failure') and an explicit exclusion with the correct alternative ('not to validate a specific number -- use validate_iban for that'). Routing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a financial institution by its BIC (Business Identifier Code, also called SWIFT code) and return the matching bank's details.
Accepts an 8-character (head office) or 11-character (branch) BIC. Returns JSON with bic, bic8, bank_name, city, country_code, country_name, sepa, the institution type and its status. Use this to resolve a BIC to a human-readable bank, to confirm a SWIFT code is real, or to enrich a validated IBAN with institution details. An unknown or malformed BIC returns an error result rather than a guess; codes are never fabricated. Requires an API key on the Basic plan or above, or a free key whose address has a verified ibanchecker.cash account.
| Name | Required | Description | Default |
|---|---|---|---|
| bic | Yes | An 8- or 11-character ISO 9362 BIC/SWIFT code, case-insensitive (e.g. 'DEUTDEFF' or 'DEUTDEFF500'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnly/idempotent/openWorld/non-destructive) by disclosing the auth requirement (Basic plan or above, or verified free key), the error behavior for unknown/malformed codes, and a no-fabrication guarantee. It also enumerates the returned JSON fields even without an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose and length semantics, then use cases, then error/auth caveats. It is somewhat long with the full field enumeration, but each sentence carries distinct information and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter lookup with no output schema: the description covers input format, use cases, return fields, error semantics, and auth prerequisites, leaving no material gap an agent would need before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that 8 characters denote a head office and 11 a branch, which the schema's pattern/length constraints do not convey. That interpretive value earns an above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Look up a financial institution by its BIC') and immediately resolves the BIC/SWIFT alias ambiguity. It is clearly distinguishable from the sibling IBAN-oriented tools (validate_iban, extract_ibans_from_text, get_iban_format) since it operates on BIC codes, not IBANs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names three concrete scenarios for use: resolving a BIC to a bank, confirming a SWIFT code is real, and enriching a validated IBAN. However, it does not explicitly name alternatives or state when NOT to use it, so alternative-routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a batch of up to 100 IBANs in one call, applying the same ISO 13616 checks as validate_iban (country, length, BBAN structure, MOD-97).
Returns JSON with count, valid_count, invalid_count and results, one entry per IBAN in input order, each shaped like a validate_iban result.
Use this instead of calling validate_iban in a loop when checking a list (e.g. a payment file or a column of supplier accounts). Split inputs larger than 100 into multiple calls. Account numbers are validated in memory and never stored. Requires an API key on the Basic plan or above; a free key whose address has a verified ibanchecker.cash account can try it with up to 10 IBANs per call. Each IBAN counts as one request.
| Name | Required | Description | Default |
|---|---|---|---|
| ibans | Yes | Array of 1 to 100 IBAN strings to validate. Case-insensitive; spaces are tolerated. Order is preserved in the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by disclosing that validation happens in memory and data is never stored, the plan requirement (Basic+ or limited free tier with verified account, 10 IBANs), and the billing semantics (each IBAN counts as one request). These are the behavioral facts an agent needs to decide whether to call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and batch limit, then return shape, then routing guidance, then constraints. Every sentence carries distinct information; nothing is padding or redundant with structured fields except the item cap, which is brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description fully specifies the response shape (count, valid_count, invalid_count, results aligned to input order, each entry like a validate_iban result). Combined with the check types, storage posture, and access requirements, nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is fully documented (case-insensitivity, space tolerance, order preservation, 1–100 range). The description's restatement of the 100-item cap and input-order guarantee adds no meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (validate), resource (IBANs), and scope (batch of up to 100 in one call), and explicitly ties the semantics to the sibling `validate_iban` by name. An agent can distinguish it from `validate_iban` and the extract/lookup siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this instead of calling `validate_iban` in a loop when checking a list, gives concrete examples (payment file, supplier accounts column), and states the alternative behavior for oversized inputs (>100 → split into multiple calls). Both when-to-use and when-not are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a single International Bank Account Number (IBAN) against the official ISO 13616 structure for its country.
What it checks: the country code, total length for that country, the national BBAN structure, and the MOD-97 check digits. When the bank/branch code maps to a known institution, the response also includes the bank name, BIC/SWIFT code, and country.
Returns JSON with valid (boolean), iban, formatted, country, country_name, check_digits, bban, and, when the bank is recognized, bank_name, bic, bank_code, bank_city, sepa and national_check_valid. An invalid IBAN still returns a result, with valid: false, an error message and an error_code (e.g. INVALID_CHECKSUM, INVALID_LENGTH, UNKNOWN_COUNTRY); it does not throw.
Use this when you have one account number to verify. For many IBANs prefer validate_bulk_ibans; to pull IBANs out of prose use extract_ibans_from_text first. No account data is stored; validation runs in memory and is discarded. Requires an API key; a free key from ibanchecker.cash/api-docs covers 100 requests a month.
| Name | Required | Description | Default |
|---|---|---|---|
| iban | Yes | A single IBAN to validate. Case-insensitive; spaces are tolerated and ignored (e.g. 'DE89 3704 0044 0532 0130 00' or 'GB29NWBK60161331926819'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses that invalid input still returns a structured result with error_code rather than throwing, enumerates what is checked, and states that no account data is stored (in-memory, discarded) plus the API-key and quota requirement. These are exactly the operational facts an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is segmented into purpose, what-it-checks, return shape, and when-to-use, all front-loaded with the core purpose first. Given there is no output schema, the return-list sentence earns its space rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully carries return-value documentation, including valid/error fields and sample error codes, and covers auth and rate-limit constraints. An agent has everything required to call and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents case-insensitivity and space tolerance for the single 'iban' parameter, so the baseline is 3. The description adds only that validation is country-specific, which is context rather than new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb (validate) and resource (a single IBAN) plus the standard it checks against (ISO 13616 country structure). The word 'single' immediately distinguishes it from the sibling validate_bulk_ibans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit selection rule: 'Use this when you have one account number to verify,' and names both alternatives by name with their triggering conditions (validate_bulk_ibans for many, extract_ibans_from_text for prose). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0extract_ibans_from_text2 fields changedInput schema / properties / text / descriptionPrevious value: -"The text to scan for IBANs"New value: +"Arbitrary text to scan for IBANs, e.g. the body of an email or invoice. IBANs may be split across spaces or embedded in sentences."Input schema / properties / text / minLengthAdded value: +1get_iban_format2 fields changedInput schema / properties / country_code / descriptionPrevious value: -"Two-letter ISO 3166-1 country code (e.g. DE, GB, FR)"New value: +"Two-letter ISO 3166-1 alpha-2 country code, case-insensitive (e.g. 'DE' for Germany, 'GB' for the United Kingdom, 'FR' for France)."Input schema / properties / country_code / patternAdded value: +"^[A-Za-z]{2}$"lookup_bic4 fields changedInput schema / properties / bic / descriptionPrevious value: -"The BIC/SWIFT code to look up (e.g. DEUTDEDB)"New value: +"An 8- or 11-character ISO 9362 BIC/SWIFT code, case-insensitive (e.g. 'DEUTDEFF' or 'DEUTDEFF500')."Input schema / properties / bic / maxLengthAdded value: +11Input schema / properties / bic / minLengthAdded value: +8Input schema / properties / bic / patternAdded value: +"^[A-Za-z0-9]{8}([A-Za-z0-9]{3})?$"validate_bulk_ibans3 fields changedInput schema / properties / ibans / descriptionPrevious value: -"Array of IBANs to validate (max 100)"New value: +"Array of 1 to 100 IBAN strings to validate. Case-insensitive; spaces are tolerated. Order is preserved in the response."Input schema / properties / ibans / items / minLengthAdded value: +5Input schema / properties / ibans / minItemsAdded value: +1validate_iban2 fields changedInput schema / properties / iban / descriptionPrevious value: -"The IBAN to validate"New value: +"A single IBAN to validate. Case-insensitive; spaces are tolerated and ignored (e.g. 'DE89 3704 0044 0532 0130 00' or 'GB29NWBK60161331926819')."Input schema / properties / iban / minLengthAdded value: +5v1.1.2extract_ibans_from_textget_iban_formatlookup_bicvalidate_bulk_ibansvalidate_ibanScored across 5 tools
Each tool has a clearly distinct purpose: single validation, bulk validation, text extraction, format specification, and BIC lookup. The descriptions explicitly guide when to use one over another, such as preferring bulk over looping single validation.
All tool names use snake_case with a consistent verb_noun structure (validate_iban, validate_bulk_ibans, get_iban_format, lookup_bic). The longer extract_ibans_from_text still follows the same readable pattern.
Five tools is well-scoped for an IBAN validation service. Each tool covers a distinct operation and none feels redundant or excessive.
The core validation lifecycle is well covered: single, bulk, extraction from text, format lookup, and BIC resolution. A minor gap is the lack of a tool to enumerate all supported countries or list banks by country, but agents can work around this via format lookups.
Cross-border payment & banking intelligence for AI agents: SWIFT/BIC, IBAN, sanctions, FX, tracking.
Check the bank behind an IBAN before you pay: bank-code check, BIC with source, bank-level sanctions
Checksum validation for AI agents: IBAN, ISBN, EAN/GTIN, UUID, ULID. Deterministic, no auth.
Validate IBANs in 111 countries; bank directory checks for DE, AT, BE, FR, LU, NL, PT and ES.
