MCP 服务器

plinth-fx-mcp

MCP server that provides real exchange-rate data from the European Central Bank, including latest rates, currency conversion, historical rates, and time series.

README

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.