io.github.koraykoylu/ibanchecker-mcp

Official5 tools

by koraykoylu · JavaScript

IBAN validation, extraction, format specs and BIC/SWIFT lookup tools for AI assistants.

io.github.koraykoylu/ibanchecker-mcp (MCP Server)

This MCP server provides tools for IBAN validation, extraction, format specifications, and BIC/SWIFT lookup for AI assistants. It is backed by the ibanchecker.cash validation engine and is intended to expose these finance-related capabilities via the Model Context Protocol.

🛠️ Key Features

IBAN validation
IBAN extraction
IBAN format specifications
BIC/SWIFT lookup
Exposes capabilities as MCP tools (toolCount: 5)

🚀 Use Cases

Check whether a provided IBAN is valid
Extract IBAN details from user input
Verify IBAN format requirements
Look up BIC/SWIFT information

⚡ Developer Benefits

Works as an MCP server (model-context-protocol)
Focused toolset for fintech workflows
Topics include: cloudflare-workers, fintech, iban, mcp, swift-bic

⚠️ Limitations

Tool documentation is incomplete in the provided source excerpt (the table row for validate_iban is cut off).

Topics

cloudflare-workersfintechibanmcpmodel-context-protocolswift-bic

Captured live from the server via tools/list.

validate_iban

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.

Parameters1

iban

string

required

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

Raw schema

{
  "type": "object",
  "properties": {
    "iban": {
      "type": "string",
      "minLength": 5,
      "description": "A single IBAN to validate. Case-insensitive; spaces are tolerated and ignored (e.g. 'DE89 3704 0044 0532 0130 00' or 'GB29NWBK60161331926819')."
    }
  },
  "required": [
    "iban"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

validate_bulk_ibans

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.

Parameters1

ibans

array

required

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

Raw schema

{
  "type": "object",
  "properties": {
    "ibans": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 5
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of 1 to 100 IBAN strings to validate. Case-insensitive; spaces are tolerated. Order is preserved in the response."
    }
  },
  "required": [
    "ibans"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

extract_ibans_from_text

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.

Parameters1

text

string

required

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.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "description": "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."
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_iban_format

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.

Parameters1

country_code

string

required

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

Raw schema

{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "pattern": "^[A-Za-z]{2}$",
      "description": "Two-letter ISO 3166-1 alpha-2 country code, case-insensitive (e.g. 'DE' for Germany, 'GB' for the United Kingdom, 'FR' for France)."
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

lookup_bic

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.

Parameters1

bic

string

required

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

Raw schema

{
  "type": "object",
  "properties": {
    "bic": {
      "type": "string",
      "minLength": 8,
      "maxLength": 11,
      "pattern": "^[A-Za-z0-9]{8}([A-Za-z0-9]{3})?$",
      "description": "An 8- or 11-character ISO 9362 BIC/SWIFT code, case-insensitive (e.g. 'DEUTDEFF' or 'DEUTDEFF500')."
    }
  },
  "required": [
    "bic"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md5 KBView on GitHub

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_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 92 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. Every tool except get_iban_format needs an API key (see API key).

code

https://mcp.ibanchecker.cash/mcp

Claude Code

bash

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:

json

{
  "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"
      }
    }
  }
}

Local stdio server

Run the server locally over stdio (requires Node 18+):

json

{
  "mcpServers": {
    "ibanchecker": {
      "command": "npx",
      "args": ["-y", "@ibanchecker/mcp"],
      "env": {
        "IBANCHECKER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Example

Calling validate_iban with DE89370400440532013000 returns:

json

{
  "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.

API key

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
`validate_iban`	yes	yes	yes	yes
`validate_bulk_ibans`	no	up to 10 IBANs a call	up to 100	up to 100
`lookup_bic`	no	yes	yes	yes
`extract_ibans_from_text`	no	up to 5,000 characters a call	trial with a verified account	up to 50,000
`get_iban_format`	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).

Project layout

code

.
├── 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:

bash

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.

Install

Tools (5)

validate_ibanvalidate_bulk_ibansextract_ibans_from_textget_iban_formatlookup_bic

Configuration

Environment variables

IBANCHECKER_API_KEYsecret

API key from ibanchecker.cash/api-docs, needed for the validation and extraction tools (the free key covers 100 requests a month).

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ibanchecker-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ibanchecker/mcp@1.4.0"
      ],
      "env": {
        "IBANCHECKER_API_KEY": "<YOUR_IBANCHECKER_API_KEY>"
      }
    }
  }
}

io.github.koraykoylu/ibanchecker-mcp (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

validate_iban

validate_bulk_ibans

extract_ibans_from_text

get_iban_format

lookup_bic

ibanchecker-mcp

Quick start: hosted remote server

Local stdio server

Example

API key

Project layout

Self-hosting the Worker

License

Install

Configuration

Related servers