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).```
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 ` / `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: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.
