跳到主要内容
FinCode

MCP server for AI coding tools

Expose the FinCode directory to Cursor, Claude Code and Claude Desktop over the Model Context Protocol: bank code lookups, IBAN validation and institution search straight from the assistant.

本文档适用于 API V1。

Overview

fincode-mcp is a stdio MCP server that wraps this API. Instead of guessing a SWIFT code or inventing an IFSC, the assistant calls a tool and answers from the same dataset the API serves. Fourteen tools are exposed: nine identifier tools (one per family, plus IBAN validation) work without an API key, the five directory tools need one. The server runs locally on Node.js 18+ and talks to the API over HTTPS.

Install

Two install sources, same server: the npm package once it is published, or the tarball attached to every mcp-v* release, which needs no npm account and works today. There is nothing to install globally - npx fetches the source on each start. Running from a source checkout is also supported: build the workspace package and point your AI tool at the compiled entry point.

bash
# tarball from the latest mcp-v* release (no npm account needed)
npx -y -p https://github.com/WilliamWangL/fin-code/releases/download/mcp-v0.1.0/fincode-mcp-0.1.0.tgz -- fincode-mcp

# npm package, once published
npx -y fincode-mcp

# or from a source checkout
git clone https://github.com/WilliamWangL/fin-code.git
cd fin-code/apps/mcp && npm install && npm run build
node dist/index.js

Cursor

Register the server in ~/.cursor/mcp.json for every project or in .cursor/mcp.json for one, then reload the window. Remove the env block to run keyless. Before the first npm release, swap args for ["-y", "-p", "<release tarball URL>", "--", "fincode-mcp"].

~/.cursor/mcp.json
{
  "mcpServers": {
    "fincode": {
      "command": "npx",
      "args": ["-y", "fincode-mcp"],
      "env": { "FINCODE_API_KEY": "sk_live_..." }
    }
  }
}

Claude Code and Claude Desktop

Claude Code registers the server with one command. Claude Desktop accepts the same mcpServers block as Cursor, inside claude_desktop_config.json.

bash
claude mcp add fincode --env FINCODE_API_KEY=sk_live_... -- npx -y fincode-mcp

Tools

Every REST lookup has its own tool with a semantically named argument, so the model chooses by identifier family rather than guessing a type. Six digits fit a UK/Ireland sort code, an Australian BSB and a card BIN: pick lookup_sort_code, lookup_bsb or lookup_bin from the user's country instead of trying all three.

ToolWhat it doesAPI key
lookup_swift_codeSWIFT/BIC code to institution, city and code layout.no
lookup_ibanValidate an IBAN and resolve the issuing institution (name, SWIFT/BIC, city).no
validate_ibanCountry, length, structure and MOD-97 checksum; parses the bank code and account number.no
lookup_ifscIndian IFSC to bank branch, with the 9-digit MICR when published.no
lookup_cnapsChinese CNAPS code to bank branch and 3-digit bank code.no
lookup_routing_numberUS ABA routing number with the checksum verdict, city and state.no
lookup_sort_codeUK/Ireland 6-digit sort code to bank branch.no
lookup_bsbAustralian 6-digit BSB to bank branch, city and state.no
lookup_bin6-8 digit card BIN/IIN to issuer, brand, type and country.no
search_banksFull-text search over institutions, with the identifiers each bank carries.yes
get_bankOne institution by id (inst_...) or slug: identifiers, website, branch count.yes
list_bank_branchesCursor-paginated branches, filterable by free text or city.yes
list_countriesCountry reference data, filterable by name/code or IBAN participation.yes
get_countryOne country plus its national IBAN layout and an example IBAN.yes

Configuration

Every variable is passed through the env block of the MCP configuration. Only the API key matters for normal use; the rest exist for self-hosted deployments and slow networks.

VariableDefaultDescription
FINCODE_API_KEYunsetKey with the sk_ prefix, sent as Authorization: Bearer. Optional.
FINCODE_API_BASE_URLhttps://api.ecommica.com/v1API root including /v1; point it at a self-hosted instance.
FINCODE_MCP_TIMEOUT_MS15000Per-attempt timeout; a timeout is retried once.
FINCODE_MCP_MAX_RETRIES1Retries after the first attempt for 429, 502, 503, 504 and network errors.

Keyless mode and limits

Without FINCODE_API_KEY the nine identifier tools still answer, from the anonymous bucket of 10 requests per minute per IP. The directory tools reply with MISSING_API_KEY until a key is configured. With a key, every call counts against the plan quota and the remaining budget is reported back in meta.rate_limit_remaining. A valid IBAN confirms format only, never account existence - the server tells the model to say so.

How results are reported

Each tool returns one JSON document. A value missing from the dataset is an answer, not a failure: found: false with the API's error code. Transport, authentication and quota failures set isError so the assistant stops and explains what to fix. Error codes match the API exactly, so the same troubleshooting applies as for direct HTTP calls.

CodeMeaningWhat to do
MISSING_API_KEYA directory tool was called without a key.Set FINCODE_API_KEY and restart the server.
UNAUTHORIZED / API_KEY_EXPIREDThe key is missing, invalid or revoked.Issue a new key in the dashboard.
QUOTA_EXCEEDEDThe plan's monthly quota is exhausted.Upgrade the plan or wait for the next period.
RATE_LIMITEDKeyless calls share 10 requests per minute per IP.Retry after the retry_after_seconds hint, or use an API key.
NOT_FOUNDThe value is not in the dataset.Report it as unknown data; not a failure.
INVALID_IBAN, INVALID_IFSC, ...Validation failed for that identifier type.Fix the input; the message names the rule.