IBANforge

ibanforge-mcp

IBANforge 的官方 Model Context Protocol (MCP) 服务。

付款前检查 IBAN 对应的银行：支持 89 个国家/地区的验证、依据国家登记册给出的银行代码判定结果（本次发布支持 DE、AT、BE、SK、BG、CH、LI；实时列表见 llms.txt）、银行及其 BIC 和来源、银行是否支持 SEPA、SEPA Instant 和 VoP，以及银行层面的制裁信息（OFAC、EU、UN）。

这不是姓名核验（VoP、BAV、CoP），不能证明账户存在或处于开放状态，不是对收款人进行制裁筛查（仅检查银行和国家/地区），也不是获得许可的 SWIFT BIC 目录副本。目前尚未检查 BBAN 中的国家级校验位（法国 RIB 密钥、意大利 CIN、西班牙 DC、德国账号校验方法）：如果 IBAN 的 mod-97 校验正确，即使国家级校验密钥错误，结果仍会显示有效。仅执行英国模数校验和波兰结算号码校验位检查。

适用于商业软件和 AI Agent：无需电子邮件即可获取 API 密钥、通过银行卡购买预付套餐，并可在 HTTP API 上使用 x402 微支付。

免费访问

本 README 特意不列出具体数值：已发布的软件包会保持原样，直到下一次发布，而服务的额度可能会变化。当前生效的数值可通过 rate-limits.yml 和 GET /v1 实时获取。

• 远程 MCP，无需安装： https://api.ibanforge.com/mcp 无需密钥或钱包即可响应完整的工具调用，但受其按来源地址计算的独立额度限制（rate-limits.yml 中的 mcp_anonymous），批量请求按每个 IBAN 计数。该额度与下文的 REST 试用额度分开。使用 Authorization: Bearer 标头中的 API 密钥时，调用计入该密钥的额度，与 REST API 的计数方式完全相同。
• 本软件包，无需密钥即可使用： validate_iban 通过 REST API 的免密试用额度（rest_anonymous_trial）调用，按来源地址计数；每个响应的 trial 区块会显示剩余调用次数和计数重置时间。其他付费工具需要密钥、预付额度或 x402。
• 无需电子邮件或银行卡的密钥： 使用空请求体向 POST https://api.ibanforge.com/v1/keys/generate 发送请求，会返回一个 ifk_ 密钥，该密钥在每个端点上都有独立额度（anonymous_key）。在 POST /v1/keys/claim 中使用发送到指定邮箱地址的验证码认领后，同一个密钥即可获得更高额度（free_tier；见继续使用同一个密钥）。

工具

工具	描述	费用（USDC）
validate_iban	验证单个 IBAN（ISO 13616 mod-97），解析 BIC，分类发行方（银行/EMI/vIBAN），并标明 SEPA 和 VoP 状态	0.005
batch_validate_iban	一次调用最多验证 100 个 IBAN	每个 0.002
lookup_bic	在 121k+ 个 BIC 条目中查询 BIC/SWIFT（其中 39k+ 个经 GLEIF 补充了 LEI 信息）	0.003
lookup_ch_clearing	在 1,100+ 个 SIX BankMaster 条目中查询瑞士 BC-Nummer / IID——包含完整支付渠道参与信息（SIC、euroSIC、CHF 即时支付）和 QR-IID	0.003
check_compliance	付款前检查：IBAN + 针对收款方银行（BIC8）和国家/地区匹配的制裁名单（OFAC、EU、UN），绝不根据收款方姓名匹配 + FATF + SEPA Instant + VoP 就绪情况 + 风险评分（0-100）	0.02
validate_payment_reference	验证结构化付款参考信息——RF/ISO 11649（“SCOR”）、瑞士 QR 参考信息（“QRR”）、比利时 OGM/VCS、芬兰 viitenumero——每种格式均依据发布规则的带日期文件进行验证。提供 IBAN 可获取 QRR↔QR-IBAN 配对判定（按一次 validate_iban 调用计费）	免费
check_postal_address	在 2026 年 11 月规则变更前，依据 SPS（SIX）、HVPS+（T2）或 Fedwire 规则检查结构化 ISO 20022 邮政地址——每条检查结果均注明来源文件和日期	免费
check_swiss_qr_bill	根据结构规则检查瑞士 QR 账单的文本内容；不验证受益人账户	免费
audit_creditor_file	审核完整的债权人/供应商文件（CSV/XLSX）：逐行检查 IBAN、银行、BIC、SEPA 覆盖范围和地址合规性，并进行文件级检查（重复项、BIC 不匹配、地址与 IBAN 国家/地区不符）。免费预览会遮蔽 IBAN；完整注释报告为付费交付内容	免费预览（报告：通过 Stripe 支付 CHF）
audit_status	查询由 audit_creditor_file 创建的审核任务的付款状态，并在付款后获取报告下载链接	免费
send_feedback	报告不正确的数据，或在付费答复有误时申请 x402 条款承诺的退款	免费
request_api_key	发起密钥申请，由人工在浏览器中批准——无需电子邮件、银行卡或账户。会显示一段短代码和一个可转交给人工的链接	免费
poll_api_key	人工批准后获取密钥。密钥只会交付一次，同时提供一行可粘贴到 MCP 客户端配置中的内容	免费

USDC 价格适用于 HTTP API 上的 x402 付款；只有通过该方式付款，批量验证的每个 IBAN 才会比单独验证更便宜。使用密钥或预付额度时，每次付费调用消耗一次请求或一个额度，批量调用中的每个 IBAN 各消耗一个。

在 MCP 客户端中获取长期有效的密钥

无需电子邮件、账户或表单。只需四步，人工操作约需十五秒：

1. 调用 request_api_key。先查看 status——ok 表示已生成代码。
2. 将 display_to_human 区块原样展示给人工：其中包含短代码 和链接。不要自行打开链接，也绝不要编造地址。
3. 人工打开页面，确认代码匹配后点击。页面会提供一个完全不含地址的密钥；他们可以在页面上添加地址以提高额度。
4. 调用 poll_api_key（无需参数）。状态为 approved 时会一次性返回密钥， 以及可直接粘贴的 config_line。将其保存为 IBANFORGE_API_KEY 并重新连接。

这两个工具免费，并且在免费额度用完后仍可继续使用——这正是它们的用途。

连接并获取第一个结果

远程 MCP：无需安装或密钥

在兼容的 MCP 客户端中使用 Streamable HTTP URL **https://api.ibanforge.com/mcp**。 此远程服务根据来源地址设有独立限额（参见免费访问）； 批次中的每个 IBAN 都计为一个单位。使用 Authorization: Bearer ifk_... （或 X-API-Key）发送密钥后，工具调用会像 REST API 一样计入该密钥的限额，而不再使用 此限额。不会读取 URL 中的密钥。

对于 Claude Code：

claude mcp add --transport http ibanforge https://api.ibanforge.com/mcp
# with your key:
claude mcp add --transport http ibanforge https://api.ibanforge.com/mcp --header "Authorization: Bearer ifk_your_key"

在 Claude 和 Claude Desktop 中，创建自定义连接器时，请在请求标头下添加密钥。 ChatGPT 不会向连接器发送密钥：在 ChatGPT 中，远程服务仍使用无密钥限额。

提问：“验证 DE89370400440532013000，识别银行，并说明结果能证明和不能证明什么。”查看 valid、bank_code_check 以及任何 BIC 的来源信息。 校验和有效并不能证明账户存在或属于某个指定的人。

已安装的 MCP：可选使用可重复使用的密钥访问 REST

对于 Claude Desktop，请将以下内容添加到其 MCP 配置中；对于 Cursor，请使用 .cursor/mcp.json：

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["-y", "ibanforge-mcp"]
    }
  }
}

对于 Claude Code：

claude mcp add --transport stdio ibanforge -- npx -y ibanforge-mcp

此配置有意设置为无需占位符密钥即可运行。已安装的软件包会调用 REST API：不使用密钥时， validate_iban 会使用其无密钥试用额度，该额度与远程 MCP 的额度分开计算。请始终查看返回的限额； 各项免费工具都有各自的保护措施。试用结束后，单个 IBAN 验证可能仅返回格式检查，并标记为 _degraded: true 和 _scope: "format_only"。其中不包含银行、SEPA 或合规性判定。 被拒绝的批次会返回错误，不会拆分成单独的免费请求。

继续使用同一个密钥

创建密钥时不提供地址：

curl -X POST https://api.ibanforge.com/v1/keys/generate

安全保存返回的 api_key，并将其作为 IBANFORGE_API_KEY 添加到 MCP 服务的 env 对象中，然后重新连接客户端。不要粘贴占位符密钥，也不要为每次对话创建新密钥。 密钥的初始额度为免费访问中给出的额度；请查看 monthly_limit，因为临时保护措施可能会降低该额度。 密钥提供稳定的身份标识、专属配额以及 GET /v1/keys/usage。

使用后，可以通过 POST /v1/keys/claim 认领同一个密钥，并使用 Authorization: Bearer ifk_…，切勿将密钥放在请求正文中。向为此明确提供的地址发送六位数代码，可提高密钥额度，并在每个新周期续期。使用该密钥进行的 x402 付款可一次性提高额度，不会续期。具体数值对应于 rate-limits.yml 中的 free_tier。未经授权，不要推断地址或发起付款。预付额度也可与已配置的密钥配合使用：每次调用扣除一个额度，批次中的每个 IBAN 也扣除一个额度。

此软件包没有钱包，不会为 x402 请求签名或自动付款。 它会返回 API 的付款要求。如需按次付款，请使用支持 x402 的 HTTP 客户端，并遵循付款指南。

无需猜测即可恢复

• isError: true：没有成功的工具结果。检查 error、status、cause 和 _hint。
• 402：遵循现有密钥的原因说明，或配置可用的密钥；不要创建密钥来绕过限额。
• 429：如有 retry_after，请等待指定时间。客户端会转发 HTTP Retry-After 的值。
• request_timeout / transport_error：未收到完整响应。这不是银行判定。
• _degraded: true：仅检查了格式。绝不可将其用作银行或 SEPA 可达性的证据。

请求会在 30 秒后超时，包括读取响应正文的时间。不会自动重试：中断的上传或其他 POST 请求可能已经处理。

示例

添加服务后，向你的 AI Agent 提问：

• "验证 IBAN DE89 3704 0044 0532 0130 00，并告诉我其银行代码对应哪家银行"
• "CH93 0076 2011 6238 5295 7 的银行代码是否已分配？"（该 IBAN 通过 mod-97 校验；SIX 登记簿中没有机构使用其银行代码，因此 bank_code_check.reason 为 not_allocated）
• "查询 BIC UBSWCHZH80A"
• "查询瑞士 BC-Nummer 230"
• "对 IBAN GB29 NWBK 6016 1331 9268 19 执行合规检查"
• "批量验证以下 5 个 IBAN：…"

配置

环境变量	默认值	说明
IBANFORGE_API_BASE	https://api.ibanforge.com	用于覆盖自托管或预发布实例的地址
IBANFORGE_API_KEY	(unset)	可选的真实 Bearer ifk_* 密钥；在密钥可用前可不设置
IBANFORGE_TIMEOUT_MS	30000	完整 HTTP 响应的截止时间，1–120000 ms；无效值将使用默认值

数据来源

• 银行代码判定：此版本涵盖德国（Bundesbank）、奥地利（OeNB）、比利时（NBB）、斯洛伐克（NBS）、保加利亚（BNB）以及瑞士和列支敦士登（SIX BankMaster）的国家登记簿；如果登记簿中没有某个代码，则判定为 not_allocated。其他地区使用部分登记簿或复合映射，未查到并不代表拒绝。实时列表见 llms.txt。
• 超过 12.1 万条 BIC 记录（指记录数，而非机构数）。GLEIF 和国家登记簿每月更新；SwiftCodes 数据是 2018 年 1 月冻结的 SWIFT 目录公开副本，导入时未作更改，目前仍约占整个目录的三分之二。实时精确数量见 api.ibanforge.com/llms.txt。来源：
  • PeterNotenboom/SwiftCodes（采用 MIT 许可证的 SWIFT 目录公开副本，数据冻结于 2018 年 1 月）
  • GLEIF BIC-LEI 映射（唯一包含 LEI 代码的记录，超过 3.9 万条）
  • EBA Clearing STEP2 SCT（官方 SEPA 可达 PSP 目录）
  • Deutsche Bundesbank BLZ（官方季度文件）
  • NBP EWIB（官方波兰银行登记簿）
  • SIX Group BankMaster（瑞士 BIC）
• 超过 1,100 个 BC-Nummern，来自官方 SIX BankMaster CSV
• EMI / vIBAN 分类：来自精选的非银行发行方（EMI、支付机构、数字银行）；对于西班牙银行代码，还参考 EBA PSD2 登记簿。实时数量见 llms.txt
• VoP 就绪情况：来自 EPC 收款人验证方案登记簿（vop.csv），与其他合规清单每周一同更新
• 制裁名单：来自 OFAC、EU 和 UN 名单，根据收款人的银行（BIC8）和国家进行匹配，绝不根据收款人姓名匹配

链接

• 网站
• API 文档
• OpenAPI 3.1 规范
• x402 发现
• 问题跟踪器

法律

通过此服务发出的调用会访问托管 API，并受 服务条款（隐私政策、 DPA）约束。验证仅确认 IBAN 结构 和登记簿数据，并不能确认账户是否存在或属于任何人；汇款前请按姓名核实收款人。

许可证

Apache-2.0