Exchange Rates MCP Server

@cyanheads/exchange-rates-mcp-server Convert currencies, get FX rates, and query historical Frankfurter v1 exchange rate data via MCP. STDIO or Streamable HTTP. 7 Tools • 1 Opt-in Tool • 2 Resources

Public Hosted Server: https://exchange-rates.caseyjhand.com/mcp

Overview

Daily exchange rates from Frankfurter v1, with current currency discovery and historical coverage from 1999-01-04. Convert amounts, pull point-in-time or historical rates, summarize a full date range, and run SQL over staged series. Historical availability includes retired currencies and is checked against the requested data. Responses identify source: "Frankfurter v1" and rate_type: "Daily rate (Frankfurter v1)"; the v1 payload does not identify individual providers. No API key required.

Tools

DataCanvas (DuckDB) is on by default. Set CANVAS_PROVIDER_TYPE=none to turn it off: the three fx_dataframe_* tools then drop out of tools/list, and fx_get_timeseries returns ranges inline when canvas_id is omitted; explicit staging fails canvas_unavailable. The Claude Desktop bundle (.mcpb) ships without DuckDB's native binding, so it runs with DataCanvas off. fx_dataframe_drop additionally needs FX_ENABLE_CANVAS_DROP=true.

The four rate and conversion tools accept base as an alias of base_currency; pair tools also accept quote for quote_currency. Send either spelling for a field, never both. Advertised schemas use the canonical names.

Currency values, including symbols, are trimmed and uppercased. Point dates accept YYYY-MM-DD or literal latest (also the default); range dates require YYYY-MM-DD. Advertised date patterns preserve handler-level invalid_date_format errors for malformed, blank or impossible calendar dates. Future range errors recommend an end_date today or earlier; end_date remains required.

Resources

All resource data is also reachable via tools — use fx_list_currencies or fx_get_rates for programmatic access.

Skill

exchange-rates-guide covers historical currency coverage, observed-day summaries, paging and SQL comparisons. It ships with npm, Docker and MCPB installs and is available over MCP at skill://exchange-rates-guide/SKILL.md.

Cancelling a tool call or resource read stops its upstream fetch, response-body read, and retry backoff. V1 requests retain two retries and a 10-second timeout per attempt within a 12-second total budget per read. Optional coverage metadata gets one 1-second request without retries.

Capability reference

fx_list_currencies tool

• Optional include_retired (default false) adds historical codes absent from current v1 discovery
• Returns currencies: [{ code, name, start_date?, end_date? }], count, source and as_of (the latest served daily rate date), sorted alphabetically by code. Coverage dates come from optional official ECB metadata and describe outer bounds, not uninterrupted availability. A dated end_date does not itself imply retirement.
• Metadata is cached for a day and queried only for the default official v1 base. Unavailable metadata leaves current discovery intact with a notice; valid v1 rate requests never depend on metadata.
• Default discovery lists current currencies; include_retired: true adds historical codes when metadata is available. Historical requests validate against their unfiltered EUR snapshot or raw served range, so retired codes remain usable on dates where they have observations. Unknown codes fail unsupported_currency with sorted accepted/rejected codes and the input field; current currencies without historical observations fail upstream_no_data.

fx_get_rates tool

• base_currency required; date optional (default latest, history from 1999-01-04, no future dates); optional symbols array narrows the response and must name at least one code
• Returns a rates map (quote code → rate), the actual rate_date, and date_snapped: true when a weekend/holiday request snapped to the prior business day
• Naming the base currency in symbols is valid — answered locally with a rate of 1 rather than sent upstream
• Missing observations from a served snapshot identify the offending field and sorted, deduplicated missing_codes; unknown currencies retain unsupported_currency precedence. A response without any snapshot remains an unattributed upstream_no_data failure.
• Typed failures: invalid_date_format, unsupported_currency, date_out_of_range, upstream_no_data

fx_get_rate tool

• base_currency, quote_currency required; date optional (default latest, history from 1999-01-04, no future dates)
• Returns rate, rate_date, and date_snapped: true when a weekend/holiday request snapped to the prior business day
• Every pair uses quote EUR leg / base EUR leg from one unfiltered EUR snapshot without intermediate rounding; EUR's leg is 1. Same-currency pairs return 1 only on actual observation dates.
• Typed failures: invalid_date_format, unsupported_currency, date_out_of_range, upstream_no_data

fx_convert_currency tool

• base_currency, quote_currency, amount (must be > 0) required; date optional (default latest, history from 1999-01-04, no future dates)
• Handles EUR↔any, any↔EUR, and cross-rate pairs (e.g. USD→JPY) in a single upstream call
• Returns quote_amount as the unrounded JavaScript-number amount * rate product, rate, rate_date, date_snapped, plus rate_type and source provenance. No currency minor-unit rounding policy is applied; formatted rates use quote currency per base currency.
• Typed failures: invalid_date_format, unsupported_currency, date_out_of_range, upstream_no_data

fx_get_timeseries tool

• base_currency, quote_currency, start_date, end_date required (history from 1999-01-04, no future dates, start ≤ end); optional canvas_id appends to an existing canvas
• Optional integer limit (default 500, minimum 0) bounds returned observations, clamping values above 500 with a notice. limit: 0 returns summary and metadata with empty rates; a nonempty inline result then points next_start_date at the first observation. Repeat with a positive limit to advance. Counts, summary, bounds, staging eligibility and complete staged tables are independent of the limit.
• Inline results page at up to 500 observed publication days — rate_count is always the range total; truncated: true plus next_start_date continue the page
• Ranges over FX_TIMESERIES_CANVAS_THRESHOLD_DAYS (default 90 days) are considered for DataCanvas staging. Series over the 40,000-character preview budget return spilled: true, canvas_id, and table_name; smaller series and deployments with CANVAS_PROVIDER_TYPE=none page inline
• A same-currency pair returns 1 on actual observation dates. Every non-identity row requires both EUR legs on that same date; missing legs never fabricate observations. Membership uses all raw served dates before inclusive clipping, preserving weekend-only empty windows.
• Missing either leg on a served in-window day produces a notice with the affected day count and first/last dates. Each day counts once, even if both legs are absent; weekends, holidays and clipped prior dates do not count. Statistics cover observed days only. Coverage and delivery notices coexist; truncated describes omitted observations in delivery, not missing upstream coverage.
• An empty range (only weekends/holidays) returns rate_count: 0 with an explanatory notice, distinguishable from an error
• Long ranges that fit the inline preview release their newly acquired canvas; failed or cancelled staging does too. A supplied canvas remains available.
• An explicit canvas_id always stages the complete result, including short and empty ranges, using rate DOUBLE. Each table name has a fresh identifier suffix; repeated and concurrent calls preserve all earlier tables. Unknown IDs fail canvas_not_found; disabled DataCanvas fails canvas_unavailable. truncated is false when the preview includes every observation.
• Nonempty results include summary: { mean, min: { rate, date }, max: { rate, date }, first: { rate, date }, last: { rate, date }, change_pct }. It covers all observations in the requested interval before paging or staging; a continuation summarizes its shorter requested interval. Tied extrema select the earliest date; singleton and identity movement is 0. Empty series omit summary. Mean is the unweighted arithmetic average of daily observations, not a tax-authority or accounting-policy prescription.

fx_dataframe_describe tool

• canvas_id required (from a prior fx_get_timeseries call)
• Retu