fx-mcp-server

A small MCP (Model Context Protocol) server that gives an MCP client — Claude Desktop, Claude Code, the FastMCP inspector, etc. — two finance-related tools:

Built with FastMCP, the server speaks MCP over stdio, so any MCP-compatible client can spawn it as a subprocess and call its tools directly from a chat conversation.

How it works

src/
├── server.py             # MCP entrypoint — registers the `convert` and `validate_iban` tools
├── fx_rate_converter.py  # Currency math: looks up rates and does the conversion
├── fx_rate_fetcher.py    # Fetches the ECB daily reference-rate XML feed and caches it as JSON
└── iban_validator.py     # Wraps the `schwifty` library to validate IBAN structure/checksum

data/
└── fx_rates.json         # Local cache of the last-fetched ECB rates (auto-generated on first `convert` call, gitignored)

• convert(source, destination, amount) — calls fx_rate_fetcher.get_fx_rates(), which downloads the ECB's eurofxref-daily.xml feed, converts it to JSON, writes it to data/fx_rates.json, and returns it. Rates are EUR-based, so a conversion is computed as (amount / rate[source]) * rate[destination]. Every call re-fetches from ECB, so it requires network access and always reflects the latest published rates (ECB updates once per business day, around 16:00 CET).

• validate_iban(iban) — delegates to the schwifty library, which checks the IBAN's country-specific format and the mod-97 checksum. It only validates structure, not whether the account actually exists at a bank.

Related MCP server: MCP-valider_iban

Prerequisites

• Python 3.13

• uv — used by FastMCP to install and run the server in an isolated environment

• Claude Desktop (if you want to use the tools from a chat conversation)

Install uv if you don't already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Project setup

1. Clone/open this repo and create a virtual environment however you prefer (uv venv, python -m venv .venv, etc.), then install the dependencies:

   pip install -r requirements.txt

   requirements.txt is a pinned snapshot of the working environment, generated with:

   pip freeze > requirements.txt

   Regenerate it the same way any time you add or upgrade a dependency, so the pinned versions stay in sync with what's actually installed.

2. Sanity-check the server definition before running anything — this loads server.py and reports the tools it exposes, or any import/registration errors:

   fastmcp inspect /absolute/path/to/your/fx-mcp-server/src/server.py

3. (Optional) Run it against the interactive FastMCP dev inspector to call the tools by hand and watch requests/responses:

   fastmcp dev inspector /absolute/path/to/your/fx-mcp-server/src/server.py

Installing into Claude Desktop

FastMCP can register the server with Claude Desktop directly. Replace the path below with the absolute path to server.py on your machine (pwd inside src/ will give you it):

fastmcp install claude-desktop /absolute/path/to/your/fx-mcp-server/src/server.py \
  --python 3.13 \
  --with-requirements requirements.txt

This writes an entry into Claude Desktop's MCP config pointing at this server, using Python 3.13 and the dependencies listed in requirements.txt.

Then, in Claude Desktop:

1. Restart Claude Desktop if it was already open.

2. Click the + icon in the connectors panel.

3. You should see fx-mcp-server listed — enable it.

That's it — convert and validate_iban are now available as tools Claude can call during a conversation. Try asking things like:

Convert 100 USD to INR

Is DE89370400440532013000 a valid IBAN?

Troubleshooting

• print() statements break the server. MCP over stdio uses stdout as the message channel between the client and server. Any stray print() in the server or its imports corrupts that stream and Claude Desktop will fail to talk to the tool (often silently, or with a generic connection error). Run fastmcp inspect first — it will surface most of these — and replace any print() calls with Python's logging module instead, which writes to stderr and won't interfere with the protocol.

• Check the Claude Desktop MCP logs when a tool fails to install, connect, or crashes at runtime:

  cat ~/Library/Logs/Claude/mcp.log

  This shows the stdout/stderr of the server subprocess and is usually the fastest way to see the real exception.

• convert fails with a currency error — the source/destination currency code isn't in the ECB feed (it only covers the ~30 currencies the ECB publishes against EUR). Check data/fx_rates.json for the supported list.

• convert requires network access — it fetches ECB rates live on every call; if you're offline it will raise an error rather than silently falling back to the cached data/fx_rates.json.