ibanchecker-mcp
ibanchecker-mcp
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 90 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.
Quick start: hosted remote server
The easiest path is the hosted endpoint. Nothing to install or deploy.
https://mcp.ibanchecker.cash/mcpClaude Code
claude mcp add --transport http ibanchecker https://mcp.ibanchecker.cash/mcpClaude Desktop (claude_desktop_config.json), via the mcp-remote bridge:
{
"mcpServers": {
"ibanchecker": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.ibanchecker.cash/mcp"]
}
}
}Related MCP server: mcp-europe-business
Local stdio server
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"
}
}
}
}Example
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 or 401 bad key), the tool result is flagged with isError: true and a human-readable message, so the assistant can react rather than crash.
API key
The underlying REST API has a free tier (1,000 requests/month). Get a key at ibanchecker.cash/api-docs and pass it as:
IBANCHECKER_API_KEYenv var (stdio mode), orAuthorization: Bearer <key>/x-api-keyheader (remote mode).
Project layout
.
├── 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.
Self-hosting the Worker
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.
License
MIT. See LICENSE.
Available Tools
5 toolsextract_ibans_from_textExtract IBANs From TextARead-onlyIdempotentInspect
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 a JSON array of the IBANs found, each with its validation result (valid, countryCode, bank details when known); 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.
| 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. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint, readOnlyHint, and destructiveHint. The description adds valuable behavioral info: input is not stored, empty list returned for no IBANs, and processing is in memory. No contradictions.
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?
The description is concise, with each sentence earning its place. Well-structured: first functionality, then usage, then behavior. No wasted text.
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?
Given simple tool with one parameter and no output schema, the description sufficiently explains the output format (JSON array with validation results) and behavior for empty input. Annotations cover safety.
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% with a good description already. The description adds nuance about IBANs possibly being split across spaces, which enhances understanding beyond the schema.
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 title and description clearly state that the tool scans text for IBANs and validates them. The verb 'extract' and resource 'IBANs from text' are specific, and it distinguishes from sibling tools like validate_iban.
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?
The description explicitly says when to use (unstructured sources like emails, invoices) and when not to (after extraction, use validate_bulk_ibans only if re-check needed). It provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_iban_formatGet Country IBAN FormatARead-onlyIdempotentInspect
Return the IBAN format specification for a country, covering 90 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.
| 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). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds that the tool covers 90 countries, returns JSON, and returns error for unsupported codes, which is useful but not extensive.
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?
Three concise sentences with front-loaded purpose. Every sentence adds value: what it does, what it returns, and when to use it. No unnecessary words.
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?
Given the tool is a simple lookup with 1 parameter, rich annotations, and no output schema, the description adequately covers the return format, country coverage, and error handling. It is complete for the tool's complexity.
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 describes the parameter well. The description adds that the country code is case-insensitive, which is not explicitly in the schema pattern. No nested objects or enums, so additional meaning is limited.
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 'Return the IBAN format specification for a country' with specific output fields (length, BBAN layout, example, SEPA flag) and explicitly distinguishes from sibling validate_iban.
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 states when to use (understand structure, build masks, explain failure) and when not to (to validate a specific number), and names the alternative tool validate_iban.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_bicLook Up Bank by BIC/SWIFTARead-onlyIdempotentInspect
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 the bank name, city, ISO country code, SEPA membership, and (when available) the official website and Wikidata entity. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| bic | Yes | An 8- or 11-character ISO 9362 BIC/SWIFT code, case-insensitive (e.g. 'DEUTDEFF' or 'DEUTDEFF500'). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context: returns specific JSON fields, error handling (no fabrication), and that unknown codes return 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?
The description is concise yet comprehensive: starts with purpose, then format, return fields, usage, and error behavior. No redundant sentences.
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?
Given the simple 1-param tool with no output schema and rich annotations, the description fully covers what an agent needs: input format, output fields, error handling, and use cases.
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?
The schema has 100% coverage with pattern and length constraints. The description adds meaning: case-insensitivity, head office vs branch distinction, and example formats, surpassing schema details.
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 clearly states it looks up a financial institution by BIC/SWIFT code, specifies the valid lengths, and lists the returned details. It is distinct from sibling tools which deal with 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?
Explicitly states when to use: resolving BIC, confirming SWIFT code validity, enriching IBAN. It also describes behavior for unknown/malformed input. No explicit when-not, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_bulk_ibansValidate Multiple IBANsARead-onlyIdempotentInspect
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 a JSON array of per-IBAN results in the same order as the input, each with valid, countryCode, an optional reason for failures, and bank details when the code is recognized, plus a summary count of valid vs. invalid entries.
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.
| 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. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: account numbers are never stored, case-insensitivity, space tolerance, order preservation, and detailed return structure (per-IBAN results with valid, countryCode, reason, bank details, summary count). No contradictions.
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?
The description is concise with three sentences covering purpose, return format, and usage guidance. It is front-loaded with the core action and immediately differentiates from the sibling tool. Every sentence serves a purpose without redundancy.
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?
Despite no output schema, the description fully explains the return value (JSON array with per-IBAN fields and summary count). It covers validation rules, privacy (not stored), and batch limit. All necessary context for correct use is provided.
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% with a description for the `ibans` parameter. The description adds meaning beyond the schema: case-insensitivity, space tolerance, and order preservation. This extra detail justifies a score above the baseline of 3.
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 clearly states the tool validates a batch of up to 100 IBANs using ISO 13616 checks, explicitly distinguishing it from the sibling `validate_iban` by noting it is for batch processing. The verb 'Validate' and resource 'batch of IBANs' are specific and unambiguous.
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?
The description explicitly advises to use this tool instead of calling `validate_iban` in a loop for lists, and provides guidance on splitting inputs larger than 100. It names the alternative tool and gives concrete examples (payment file, supplier accounts).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_ibanValidate IBANARead-onlyIdempotentInspect
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 fields such as valid (boolean), countryCode, checkDigitsValid, the formatted IBAN, and an optional bank object. On a malformed input the call still succeeds with valid: false and a reason (e.g. INVALID_FORMAT, INVALID_CHECKSUM); it does not throw for invalid IBANs.
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.
| 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'). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavior: returns JSON with valid boolean, countryCode, etc.; on malformed input returns valid:false with reason rather than throwing; and states no storage. No contradiction with annotations.
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?
The description is well-structured in three paragraphs, front-loading core purpose. Each sentence adds value, though a bit verbose. No extraneous information.
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?
Given the single parameter, no output schema, and rich annotations, the description fully covers what the tool does, what it checks, return fields, error handling, and sibling differentiation. It is complete and self-contained.
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% for the single parameter 'iban' with a description. The tool description adds practical details: case-insensitivity, tolerance of spaces, and examples (e.g., 'DE89 3704 0044 0532 0130 00'). This adds value beyond the schema's basic description.
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 clearly states the tool validates a single IBAN against ISO 13616 structure per country. It uses a specific verb (validate) and resource (IBAN), and explicitly distinguishes from siblings by recommending validate_bulk_ibans for many IBANs and extract_ibans_from_text for extracting from text.
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?
The description explicitly says when to use ('when you have one account number to verify') and when not ('for many IBANs prefer validate_bulk_ibans; to pull IBANs out of prose use extract_ibans_from_text first'). It also notes that validation runs in memory and is discarded, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v1.2.0- Changed
extract_ibans_from_text2 fields changed- changed
Input 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." - added
Input schema / properties / text / minLengthAdded value: +1
- Changed
get_iban_format2 fields changed- changed
Input 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)." - added
Input schema / properties / country_code / patternAdded value: +"^[A-Za-z]{2}$"
- Changed
lookup_bic4 fields changed- changed
Input 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')." - added
Input schema / properties / bic / maxLengthAdded value: +11 - added
Input schema / properties / bic / minLengthAdded value: +8 - added
Input schema / properties / bic / patternAdded value: +"^[A-Za-z0-9]{8}([A-Za-z0-9]{3})?$"
- Changed
validate_bulk_ibans3 fields changed- changed
Input 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." - added
Input schema / properties / ibans / items / minLengthAdded value: +5 - added
Input schema / properties / ibans / minItemsAdded value: +1
- Changed
validate_iban2 fields changed- changed
Input 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')." - added
Input schema / properties / iban / minLengthAdded value: +5
5 tool updates
v1.1.2- First observed
extract_ibans_from_text - First observed
get_iban_format - First observed
lookup_bic - First observed
validate_bulk_ibans - First observed
validate_iban
TDQS
Scored across 5 tools
Each tool serves a unique purpose: extracting IBANs from text, retrieving country format specs, looking up BIC codes, and validating IBANs singly or in bulk. No overlap in functionality.
All tools use snake_case with a clear verb_noun pattern (e.g., extract_ibans_from_text, validate_bulk_ibans). Naming is uniform and predictable.
Five tools cover the essential operations for an IBAN validation service: text extraction, format info, BIC lookup, and single/bulk validation. The count is well-scoped without being excessive or insufficient.
The tool set covers the full lifecycle of IBAN handling: discovery (extraction), validation (single and bulk), format explanation, and institution lookup. No obvious gaps for a checking service.
Maintenance
Related MCP Connectors
Cross-border payment & banking intelligence for AI agents: SWIFT/BIC, IBAN, sanctions, FX, tracking.
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.
Utility data for AI agents: IBAN, EU holidays, VAT rates, time zones, ECB FX. Pay per call.
Related MCP Servers
- AlicenseAqualityAmaintenanceIBAN validation, BIC/SWIFT lookup, SEPA compliance, issuer classification and risk indicators for AI agents. 39K+ bank entries from GLEIF. Supports 75+ countries.11127 npm3MIT
- FlicenseAqualityDmaintenanceEuropean business compliance suite for AI agents — 28 tools covering tax ID validation (PT, ES, FR, DE, IT, UK, NL), IBAN verification, EU VAT rates, invoice requirements, e-invoicing rules, payment terms, labor calendar helpers, VAT breakdown calculations and invoice schema validation for 18+ European countries.28-
- AlicenseAqualityDmaintenanceVerified validation of structured identifiers — IBAN, payment cards, ISBN-13 and VIN — for AI agents. Runs the real checksum algorithms (mod-97, Luhn, mod-10, ISO 3779) instead of letting the model guess, and returns structured results with clear errors.419 npmApache 2.0

Qinisoofficial
AlicenseAqualityCmaintenanceThe deterministic fact-verification layer for AI agents. Validates the structured facts an agent emits — IBANs, payment cards, VAT and national tax IDs, crypto and bank addresses, domains, emails, phone numbers, securities and academic identifiers, plus dates, currencies and holidays — against checksums and curated authoritative data, not guesses.561Apache 2.0