
frankfurter
io.github.lineofflight/frankfurter
Convert currencies and fetch blended FX rates from 50+ institutional sources.
Documentation
frankfurter-mcp
Official Model Context Protocol server for the Frankfurter exchange-rate API. A thin, stateless proxy over Frankfurter's v2 blended multi-source reference rates.
Tools
convert— the primary tool. Convert an amount between two currencies; returns a money object{ amount, currency }rounded to the target's minor units. Passdatefor a historical rate,providerfor one institution's published rate (e.g.UST, the U.S. Treasury's quarterly reporting rate). Setdetails: trueto include the rate, effective date, and selected provider in the same call. Same-currency conversions return rate 1 and date null. Conversion uses the direct API rate, including its precision for tiny rates.get_rates— blended reference rates for the latest day or a singledate. Optionalbase,quotesandprovider(one key or an array to compare institutions). Supplyquoteswhenever the requested currencies are known. The raw-rate companion toconvert; withproviderand the provider's own base, the digits are as published, with the date they took effect. Successful calls return an array; if a provider fails, the result is{rates, errors}, retaining successful rates and identifying failures by provider. Only a complete failure setsisError. Retry only failed providers. The legacyprovidersalias still works but cannot be combined withprovider.list_currencies— supported currency, precious metal and crypto asset codes and names as{ code: name }. Optionalquerymatches a code or name fragment, case-insensitively, including historical currencies.list_providers— the institutions relayed, with key, rate type, frequency and coverage dates, to pick aprovider. Filter byquery(key/name fragment),country(country code), orcurrency(supported code, including the provider's base). Filters combine and ignore case. A provider that publishes several series also lists itsdatasets; pass a dataset key such asNBP.Basproviderto select one.
Exact currency codes and provider keys take priority over substring matches.
All results use compact JSON. Discovery without filters still returns the full catalogue;
use filters to keep agent context small. No matches returns {} for currencies or []
for providers.
For time series, historical ranges, or bulk queries, use the REST API at
https://api.frankfurter.dev/v2 directly.
Rates are daily reference rates, not real-time trading rates. Not financial advice.
Run
npm install
npm run build
npm start # listens on :3000, POST /
Docker:
docker build -t frankfurter-mcp . && docker run -p 3000:3000 frankfurter-mcp
docker run -p 3000:3000 ghcr.io/lineofflight/frankfurter-mcp:latest
The prebuilt ghcr.io/lineofflight/frankfurter-mcp:latest image is published
on each release; building from source also works.
Point any MCP client at http://<host>:3000/ (Streamable HTTP). The hosted
server is at https://mcp.frankfurter.dev/.
Configuration
PORT— HTTP port (default3000).FRANKFURTER_API_URL— upstream API base (defaulthttps://api.frankfurter.dev). Set this to a self-hosted Frankfurter instance if desired. The value must be a host root: any path prefix in it is discarded (e.g.https://example.com/apiresolves tohttps://example.com/v2/rates), so a self-hosted instance must be reachable at the host root.
Development
npm test # vitest
npm run lint # biome
License
MIT
No installation packages available.