Plinth FX MCP

A small, production-clean Model Context Protocol server that gives any MCP client (Claude Desktop, Claude Code, Cursor, ...) real exchange-rate data — latest rates, currency conversion, historical rates, and time series — from the free, no-API-key Frankfurter service (European Central Bank reference rates).

It's free and MIT-licensed. The point isn't just "currency rates in your LLM" — it's a reference for what an MCP server should look like when you actually have to run it: rate-limited, retried, observable, and validated.

Why this one

Most example MCP servers are toys that fall over the first time an LLM calls a tool in a loop or the upstream hiccups. This one ships the boring stuff that keeps a server alive in production:

• Outbound rate limiting — a token bucket caps how fast we hit the upstream, so an over-eager agent can't get you throttled.
• Exponential backoff with full jitter — transient 429/5xx/network errors are retried with capped, jittered delays that honor Retry-After.
• Structured JSON logging to stderr — one JSON object per line, ready for a log shipper. Never writes to stdout (that's the JSON-RPC channel — polluting it corrupts the session).
• Graceful shutdown — SIGTERM/SIGINT close the HTTP client cleanly.
• Input validation on every tool argument — bad currency codes, dates, or amounts fail fast with a clear, model-recoverable error instead of a stack trace.
• A real health check tool — reports version and live upstream reachability.
• Optional API-key gate — off by default (the upstream is public); flip on with one env var if you expose this server to others.

Quickstart (one command)

With uv installed, no clone or install needed:

uvx plinth-fx-mcp

Or with pip:

pip install plinth-fx-mcp
plinth-fx-mcp

The server speaks MCP over stdio. It's meant to be launched by an MCP client, not run interactively — but the command above will start and block, logging a startup line to stderr, which confirms it's healthy.

Use with Claude Desktop / Claude Code

Add this to your MCP client config (for Claude Desktop: claude_desktop_config.json; for Claude Code: claude mcp add or your project's .mcp.json):

{
  "mcpServers": {
    "plinth-fx": {
      "command": "uvx",
      "args": ["plinth-fx-mcp"]
    }
  }
}

Then ask: "Convert 250 USD to EUR, and show me how EUR/USD moved over the first week of January 2024."

Tools

Tool	What it does
latest_rates(base="EUR", symbols=None)	Latest rates for a base currency, optionally filtered.
convert(amount, from_currency, to_currency)	Convert an amount at the latest rate (computed locally).
historical_rate(date, base="EUR", symbols=None)	Rates for a base currency on a past date.
time_series(start, end, base="EUR", symbols=None)	Rates over a date range, one entry per published day.
list_currencies()	Every supported currency code with its display name.
health_check()	Server version + live upstream reachability.

Every data tool returns a JSON object with ok: true and the payload, or ok: false with error and message on failure.

Configuration

All optional. Defaults are tuned for the free public upstream.

Env var	Default	Purpose
PLINTH_API_KEY	(unset)	If set, every data tool requires a matching api_key arg.
PLINTH_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR.
PLINTH_RATE_LIMIT_REQUESTS	5	Max upstream requests per window.
PLINTH_RATE_LIMIT_WINDOW_SECONDS	1.0	Rate-limit window length.
PLINTH_MAX_RETRIES	4	Retries on transient upstream failures.
PLINTH_BACKOFF_BASE_SECONDS	0.5	Base for exponential backoff.
PLINTH_BACKOFF_MAX_SECONDS	20.0	Backoff cap.
PLINTH_REQUEST_TIMEOUT_SECONDS	15.0	Per-request timeout.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Tests mock the network (via respx), so they pass fully offline.

---

Want the whole toolkit?

This repo is one polished example. If you're building MCP servers for real and want to skip the yak-shaving:

→ MCP Server Starter Kit

Python and TypeScript templates, more worked examples, Dockerfiles, and a deploy + directory-publishing guide (how to actually get your server listed in the MCP registries). Same SRE hygiene as this repo, batteries included.

More from the brand at plinthkit.vercel.app.

License

MIT © Plinth. Exchange-rate data from Frankfurter, sourced from European Central Bank reference rates.