# ISO 20022 Navigator MCP server

[![smithery badge](https://smithery.ai/badge/kreativemanish/iso20022-navigator)](https://smithery.ai/servers/kreativemanish/iso20022-navigator)

An [MCP](https://modelcontextprotocol.io) server that gives AI assistants grounded answers
about ISO 20022 financial messaging, from the reference data behind the
[ISO 20022 Navigator](https://www.isonavigator.io/iso20022/).

Free and public. The endpoint URL is all a client needs.

Built by [Manish Patel](https://www.linkedin.com/in/kreativemanish) · Financial Systems Expert, Finance Transformation & Analytics

**Endpoint:** `https://mcp.isonavigator.io/iso20022` (Streamable HTTP, open access)

[Documentation](https://www.isonavigator.io/iso20022/mcp.html) · [Privacy](https://www.isonavigator.io/iso20022/mcp-privacy.html) · Support: i22navigatorapp@gmail.com

## Tools

All tools are read-only.

| Tool | What it answers |
|---|---|
| [`iso20022_bank_transaction_codes`](#iso20022_bank_transaction_codes) | What an ISO 20022 Bank Transaction Code (domain, family, subfamily) means, and which codes exist under a domain or family. |
| [`iso20022_message_details`](#iso20022_message_details) | What a specific ISO 20022 message is: its name, description, business area, latest version and structure size. |
| [`iso20022_legacy_and_scheme_mappings`](#iso20022_legacy_and_scheme_mappings) | Which ISO 20022 message replaces a legacy message, and which payment schemes use an ISO 20022 message. |
| [`iso20022_code_sets`](#iso20022_code_sets) | What an ISO 20022 external code set contains, what a code means, and which code sets a message uses. |

### `iso20022_bank_transaction_codes`

- **Answers:** what an ISO 20022 Bank Transaction Code means: the domain, family and subfamily codes that classify entries in bank statements and account reports, for example `PMNT-RCDT-ESCT`. It also shows which families sit under a domain, which subfamilies under a family, and where a code appears.
- **Input:** `code`, written domain-family-subfamily with hyphens. Any part can stand alone or be skipped:
  - `PMNT`: a domain, with its families.
  - `PMNT-RCDT`: a domain and family, with the subfamilies.
  - `PMNT-RCDT-ESCT`: a full code, with the three names and a description.
  - `/RCDT` and `//ESCT`: a family or a subfamily on its own (the leading slashes fix the level).
  - `/RCDT/ESCT` and `PMNT//ESCT`: two parts with one level skipped.
  - `ESCT`: no level given; every level where the code exists is returned.
- **Returns:** official names, counts, lists of the related codes, a description when one combination matches, notes and a `provenance` block. A code that is not found says where each part exists and lists the closest existing codes.
- **Example questions:**
  - What does bank transaction code PMNT-RCDT-ESCT mean?
  - Which families does the PMNT domain contain?
  - Which domains use the family RCDT?
  - Is OTHR a family or a subfamily?
- **Notes:**
  - Covers the ISO external code list. Bank-specific (proprietary) codes are outside it, so a code that is not found may be one of those.
  - Codes are matched, not meanings. To find a code for a type of transaction, browse from the domain down.
  - Combination descriptions are AI-generated and validated against the official ISO definitions.

### `iso20022_message_details`

- **Answers:** what a specific ISO 20022 message is, for example `pacs.008` or `camt.053`: its official name, a plain-English description, the business area and domain it belongs to, its latest version and the size and shape of its structure.
- **Input:** `message_id`, four letters and three digits. Any case works, and a dot, hyphen, underscore, space or a bare join all work (`pacs.008`, `PACS-008`, `pacs008`). A full identifier such as `pacs.008.001.13` is accepted too; the response describes the latest version held and notes any difference.
- **Returns:** the message name, description, business area (code, name and domain), the Navigator's functional grouping, latest version, structure statistics (total elements, maximum depth and element counts at each depth), the number of external code sets the message uses with a `next_calls` pointer to `iso20022_code_sets` for the list, notes and a `provenance` block. A message that is missing from the dataset says so and lists up to five held messages in the same business area, nearest number first.
- **Example questions:**
  - What is pacs.008?
  - Which business area does camt.053 belong to?
  - How large is the pain.001 message definition?
  - Is camt.099 still current?
- **Notes:**
  - Covers the standard variant (variant 1) of each message, at the latest version held.
  - Structure figures are element counts from the message definition. The element tree itself is outside this tool's response. Counts cover every declared element: optional elements and every alternative of a choice are counted alongside mandatory ones, so the figures describe the size of the definition, and a single message instance uses a subset of it. `total_elements` also counts the two elements at depths 0 and 1 (Document container, message), which `elements_by_depth` omits.
  - The functional grouping is the Navigator's own and is separate from the ISO 20022 standard.
  - Retired messages are returned with the data load in which they were retired.
  - Descriptions are AI-generated and validated against the official ISO definitions.

### `iso20022_legacy_and_scheme_mappings`

- **Answers:** which ISO 20022 message replaces a legacy message (SWIFT MT, NACHA, CHAPS legacy), for example MT103 → pacs.008, and which payment schemes use an ISO 20022 message.
- **Inputs:** `message` (a legacy or ISO 20022 message, such as `MT103`, `940` or `pacs.008`) and an optional `standard` (narrows the answer to one standard or scheme, such as `SEPA`).
- **Returns:** message-level mappings with status, scheme usage, notes and a `provenance` block.
- **Example questions:**
  - What replaced MT103?
  - What is the ISO 20022 equivalent of MT940?
  - Which payment schemes use pacs.008?
  - Is tsin.004 still current?
- **Notes:**
  - Latest message version only. A version in the input (for example `pacs.008.001.08`) maps to its message (`pacs.008`).
  - Retired messages are returned with the data load in which they were retired.
  - Responses list what the Navigator has recorded. When a mapping is missing, the response says so and directs assistants to answer from the recorded data.

### `iso20022_code_sets`

- **Answers:** what an ISO 20022 external code set contains (for example `BalanceType`), what a code such as `CLBD` means, whether a code belongs to a set, which code sets a message uses, and which messages use a code set.
- **Inputs:** `message` (a code set such as `BalanceType` or `ExternalBalanceType1Code`, a code such as `CLBD`, or an ISO 20022 message such as `camt.053`), an optional `code` (checks one value in the code set) and an optional `offset` (continues a long list).
- **Returns:** for a code set, its details, its values (code, name, description) and the messages that use it with their number (`message_count`). For a code, every code set that holds it. For a message, its code sets with their number of values. Lists arrive as pipe-delimited text with a header row. Long lists come in pages; each response states whether the list is complete and the `next_offset` to continue.
- **Example questions:**
  - Which codes does the BalanceType code set contain?
  - Is CLBD a valid balance type code?
  - What does the code OTHR mean in ISO 20022?
  - Which code sets does camt.053 use?
- **Notes:**
  - Bank Transaction Code values are served by `iso20022_bank_transaction_codes`.
  - Links between code sets and messages are recorded per message, and per element is outside the data.
  - Deactivated values are returned with the data load in which they were deactivated.
  - Code set descriptions (`concept_description`) are AI-generated. Value descriptions are ISO text.
  - `navigator_group` is the Navigator's own grouping of code sets, which differs from an ISO classification.

## Getting the assistant to use it

Some assistants answer from general knowledge unless asked to use a tool, a choice made by the assistant. Adding the following line to a Project's instructions helps the assistant use the tools where they apply:

> For any question about ISO 20022 bank transaction codes, messages, their legacy equivalents (SWIFT MT, NACHA), which payment schemes use a message, what an external code set or code means, or which code sets a message uses, call the ISO Navigator connector first and answer from its data.

Other assistants may behave differently. If an answer comes without a tool call, ask again with "according to the ISO Navigator".

## Usage limits

- **Shared rate limit.** The limit is 600 calls per minute across all users together. When it is reached, the response says how long to wait before retrying.
- **Request size.** Requests up to 64 KB are accepted, and the server handles up to 20 requests at the same time.

## Data

Every response carries a `provenance` block. Its `data_baseline` (for example `4Q2025`) is the quarter of the Navigator's baseline data load, which marks when the data was added to the Navigator and differs from any ISO 20022 publication date. Check the scheme's or SWIFT's own current documentation before relying on a migration date.

The Navigator records a selection of the world's payment schemes, not all of them. The standards covered are SWIFT MT, SEPA, CIPS, NACHA / ACH, AFT, Lynx, RTR, CHAPS, Elixir, iDEAL, SIC, Bankgirot, NPP, MEPS+, RENTAS and BAHTNET. A scheme not on this list, such as T2, FedNow or Fedwire, has no recorded mappings, so the response will not list it.

Some explanations are AI-generated. Verify against official ISO 20022 and scheme documentation before use in production.

## Connect

Use the endpoint URL above. Menu names change between releases; if a label
below differs from what you see, the client's own MCP documentation is the reference.

### Claude (web and desktop app)

1. Open **Customize → Connectors**, choose **+ Add → Add custom connector**.
2. Enter a name (for example `ISO 20022 Navigator`) and the endpoint URL. Leave authentication off.
3. In a chat, use the **+** button at the lower left, then **Connectors**, and switch the connector on.

On Team and Enterprise plans an owner first adds it under **Organization settings → Connectors → Add → Custom → Web**;
members then connect it from **Customize → Connectors**. The Free plan allows one custom connector.
See [Anthropic's guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Claude Code

```
claude mcp add --transport http iso20022 https://mcp.isonavigator.io/iso20022
```

Check it with `claude mcp list`, or `/mcp` inside Claude Code. Add `--scope user` to make it available in every project.

### VS Code with GitHub Copilot

1. Run **MCP: Open User Configuration** from the Command Palette (or create `.vscode/mcp.json` in a project).
2. Add:

   ```json
   {
     "servers": {
       "iso20022": {
         "type": "http",
         "url": "https://mcp.isonavigator.io/iso20022"
       }
     }
   }
   ```

3. Run **MCP: List Servers**, select `iso20022` and start (or restart) it.
4. Use Copilot Chat in **Agent** mode; the tools appear in the tools list.

### Cursor

Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "iso20022": {
      "url": "https://mcp.isonavigator.io/iso20022"
    }
  }
}
```

Tools can be switched on and off from the chat's tools list.

### ChatGPT

Custom MCP connectors need developer mode and are available on the web. Availability depends on your plan; see
[OpenAI's guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).
In short: turn on developer mode under **Settings → Apps → Advanced settings**, choose **Create**, enter the endpoint URL
and leave authentication off, select **Scan Tools**, then **Create**. This server reads data, so read-only access is enough.

### Codex CLI

```
codex mcp add iso20022 --url https://mcp.isonavigator.io/iso20022
```

This saves the server to `~/.codex/config.toml`. Or add it there yourself (`.codex/config.toml` for one trusted project):

```toml
[mcp_servers.iso20022]
url = "https://mcp.isonavigator.io/iso20022"
```

Check it with `codex mcp list`, or `/mcp` inside a Codex session.

### Gemini CLI

```
gemini mcp add --transport http iso20022 https://mcp.isonavigator.io/iso20022
```

Add `--scope user` to make it available in every project; the default is the current project only. Or add it to `~/.gemini/settings.json` (`.gemini/settings.json` for one project):

```json
{
  "mcpServers": {
    "iso20022": {
      "httpUrl": "https://mcp.isonavigator.io/iso20022"
    }
  }
}
```

Use `httpUrl`, not `url`, which is for SSE servers. Check it with `gemini mcp list`, or `/mcp` inside a session. Which Google accounts or API keys Gemini CLI accepts is set by Google and has changed; check Google's current documentation if it will not start.

### Any other MCP client

Any client that supports remote MCP servers over Streamable HTTP can use the endpoint URL. A database-independent
health check is at `https://mcp.isonavigator.io/iso20022/health`.

## Run locally

Requires Python 3.14 and access to the Navigator database (private).

```
python -m venv .venv
.venv\Scripts\activate            # Windows; on macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
```

Put the connection string in a `.env` file as `DATABASE_URL=...`, then either:

- `python server.py` — stdio transport, for Claude Desktop or MCP Inspector
- set `MCP_TRANSPORT=http`, then `python server.py` — HTTP transport as deployed, at
  `http://localhost:8000/iso20022` (health check: `/iso20022/health`)

See the top of `server.py` for the other settings.

## Tests

```
pip install -r requirements-dev.txt
bandit -q -r . -x ./tests,./.venv
ruff check .
python -m pytest -q
```

Database tests run when `DATABASE_URL` is available.

## License

The code is under the [MIT License](LICENSE). The reference data served by the tools sits outside this repository and its license.