Skip to main content
Glama
koraykoylu

ibanchecker-mcp

ibanchecker-mcp

npm version License: MIT Model Context Protocol

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_iban

Validate a single IBAN: country, length, national BBAN structure, MOD-97 check digits, and bank details when available

validate_bulk_ibans

Validate up to 100 IBANs in one call

extract_ibans_from_text

Find and validate every IBAN inside a block of text (emails, invoices, spreadsheets)

get_iban_format

IBAN format specification for any of 90 supported countries

lookup_bic

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/mcp

Claude Code

claude mcp add --transport http ibanchecker https://mcp.ibanchecker.cash/mcp

Claude 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_KEY env var (stdio mode), or

  • Authorization: Bearer <key> / x-api-key header (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.toml

Both 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 deploy

Remove 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 tools
extract_ibans_from_textExtract IBANs From TextA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesArbitrary 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

A4.9/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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 FormatA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
country_codeYesTwo-letter ISO 3166-1 alpha-2 country code, case-insensitive (e.g. 'DE' for Germany, 'GB' for the United Kingdom, 'FR' for France).

TDQS

A4.7/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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/SWIFTA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bicYesAn 8- or 11-character ISO 9362 BIC/SWIFT code, case-insensitive (e.g. 'DEUTDEFF' or 'DEUTDEFF500').

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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 IBANsA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
ibansYesArray of 1 to 100 IBAN strings to validate. Case-insensitive; spaces are tolerated. Order is preserved in the response.

TDQS

A4.9/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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 IBANA
Read-onlyIdempotent
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
ibanYesA single IBAN to validate. Case-insensitive; spaces are tolerated and ignored (e.g. 'DE89 3704 0044 0532 0130 00' or 'GB29NWBK60161331926819').

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

  1. 5 tool updatesv1.2.0
    • Changedextract_ibans_from_text2 fields changed
      • changedInput schema / properties / text / description
        Previous 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."
      • addedInput schema / properties / text / minLength
        Added value: +1
    • Changedget_iban_format2 fields changed
      • changedInput schema / properties / country_code / description
        Previous 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)."
      • addedInput schema / properties / country_code / pattern
        Added value: +"^[A-Za-z]{2}$"
    • Changedlookup_bic4 fields changed
      • changedInput schema / properties / bic / description
        Previous 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')."
      • addedInput schema / properties / bic / maxLength
        Added value: +11
      • addedInput schema / properties / bic / minLength
        Added value: +8
      • addedInput schema / properties / bic / pattern
        Added value: +"^[A-Za-z0-9]{8}([A-Za-z0-9]{3})?$"
    • Changedvalidate_bulk_ibans3 fields changed
      • changedInput schema / properties / ibans / description
        Previous 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."
      • addedInput schema / properties / ibans / items / minLength
        Added value: +5
      • addedInput schema / properties / ibans / minItems
        Added value: +1
    • Changedvalidate_iban2 fields changed
      • changedInput schema / properties / iban / description
        Previous 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')."
      • addedInput schema / properties / iban / minLength
        Added value: +5
  2. 5 tool updatesv1.1.2
    • First observedextract_ibans_from_text
    • First observedget_iban_format
    • First observedlookup_bic
    • First observedvalidate_bulk_ibans
    • First observedvalidate_iban

TDQS

A4.7/5.0

Scored across 5 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    A
    maintenance
    IBAN validation, BIC/SWIFT lookup, SEPA compliance, issuer classification and risk indicators for AI agents. 39K+ bank entries from GLEIF. Supports 75+ countries.
    11
    127 npm
    3
    MIT
  • F
    license
    A
    quality
    D
    maintenance
    European 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
    -
  • A
    license
    A
    quality
    D
    maintenance
    Verified 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.
    4
    19 npm
    Apache 2.0
  • A
    license
    A
    quality
    C
    maintenance
    The 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.
    56
    1
    Apache 2.0