@cyanheads/exchange-rates-mcp-server

v0.1.3 pre-1.0

Convert currencies, get FX rates, and query historical ECB exchange rate data via MCP. STDIO or Streamable HTTP.

public 7 tools 2 resources protocol 2025-11-25 github cyanheads/exchange-rates-mcp-server

claude mcp add --transport http exchange-rates-mcp-server https://exchange-rates.caseyjhand.com/mcp

codex mcp add exchange-rates-mcp-server --url https://exchange-rates.caseyjhand.com/mcp

{
  "mcpServers": {
    "exchange-rates-mcp-server": {
      "url": "https://exchange-rates.caseyjhand.com/mcp"
    }
  }
}

gemini mcp add --transport http exchange-rates-mcp-server https://exchange-rates.caseyjhand.com/mcp

{
  "mcpServers": {
    "exchange-rates-mcp-server": {
      "command": "bunx",
      "args": [
        "@cyanheads/exchange-rates-mcp-server@latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "exchange-rates-mcp-server": {
      "type": "http",
      "url": "https://exchange-rates.caseyjhand.com/mcp"
    }
  }
}

curl -X POST https://exchange-rates.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Built on@cyanheads/mcp-ts-core v0.9.21

Tools

fx_list_currencies

open-world

List all supported ISO 4217 currency codes with their full names. Call this before converting to disambiguate "dollars" (USD vs AUD vs CAD vs HKD vs SGD) or to validate a user-supplied currency code. Covers the ~30 ECB reference currencies.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_list_currencies",
    "arguments": {}
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

view source ↗

fx_get_rates

Get all available exchange rates for one base currency in a single snapshot. Useful for bulk comparison and seeding downstream tools. Returns a map of quote currency → rate plus the snapshot date. Optionally filter to a subset of quote currencies via symbols.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": {
      "base_currency": "<base_currency>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    },
    "symbols": {
      "description": "Optional list of quote currency codes to filter the response. Omit to return all ~30 supported currencies.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "ISO 4217 currency code to include in the response."
      }
    }
  },
  "required": [
    "base_currency"
  ],
  "additionalProperties": false
}

view source ↗

fx_get_rate

open-world

Get the exchange rate for a currency pair on a given date (default: latest). Returns the rate, the actual rate date (which may differ from the requested date on weekends/holidays — ECB publishes business days only), and source provenance. Cross-rates are triangulated through EUR automatically. Use fx_convert_currency when you want the converted amount; use this tool when you only need the rate number.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_get_rate",
    "arguments": {
      "base_currency": "<base_currency>",
      "quote_currency": "<quote_currency>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 quote currency code (e.g. EUR). The rate is expressed as \"how many quote units per 1 base unit\"."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    }
  },
  "required": [
    "base_currency",
    "quote_currency"
  ],
  "additionalProperties": false
}

view source ↗

fx_convert_currency

open-world

Convert an amount between any two currencies at the latest or a historical rate. Returns the converted amount, the rate used, the actual rate date, and whether the date was snapped from a weekend/holiday to the prior business day. Cross-rates are triangulated through EUR automatically.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_convert_currency",
    "arguments": {
      "base_currency": "<base_currency>",
      "quote_currency": "<quote_currency>",
      "amount": "<amount>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 source currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 target currency code (e.g. EUR). The amount will be expressed in this currency."
    },
    "amount": {
      "type": "number",
      "description": "Amount in the base currency to convert. Must be a positive number."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD) for a historical rate. Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    }
  },
  "required": [
    "base_currency",
    "quote_currency",
    "amount"
  ],
  "additionalProperties": false
}

view source ↗

fx_get_timeseries

open-world

Get historical daily exchange rates for a currency pair over a date range. ECB publishes on business days only — weekends and holidays produce no entry (not snapped). Short ranges (≤90 days by default) are returned inline as a date→rate map. Long ranges spill to DataCanvas: the response carries spilled=true, a canvas_id, and a table_name. Call fx_dataframe_describe to inspect the staged table, then fx_dataframe_query to run SQL against it.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_get_timeseries",
    "arguments": {
      "base_currency": "<base_currency>",
      "quote_currency": "<quote_currency>",
      "start_date": "<start_date>",
      "end_date": "<end_date>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 quote currency code (e.g. EUR). Call fx_list_currencies to get valid codes."
    },
    "start_date": {
      "type": "string",
      "description": "ISO 8601 start date (YYYY-MM-DD). ECB data starts 1999-01-04. The actual first data point may be later if start_date falls on a weekend/holiday."
    },
    "end_date": {
      "type": "string",
      "description": "ISO 8601 end date (YYYY-MM-DD). Must be >= start_date. Future dates are not supported."
    },
    "canvas_id": {
      "description": "Optional canvas ID from a prior call. Omit on the first call to start a fresh canvas; pass the returned canvas_id to append tables to an existing canvas.",
      "type": "string"
    }
  },
  "required": [
    "base_currency",
    "quote_currency",
    "start_date",
    "end_date"
  ],
  "additionalProperties": false
}

view source ↗

fx_dataframe_describe

List tables and columns staged on a DataCanvas from a prior fx_get_timeseries call. Required first step before fx_dataframe_query — use it to discover table names and column schemas.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_dataframe_describe",
    "arguments": {
      "canvas_id": "<canvas_id>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired."
    }
  },
  "required": [
    "canvas_id"
  ],
  "additionalProperties": false
}

view source ↗

fx_dataframe_query

Run a read-only SQL SELECT against DataCanvas tables staged by fx_get_timeseries. Supports aggregations, GROUP BY, window functions, and JOINs across multiple registered tables. Run fx_dataframe_describe first to discover table names and column schemas.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fx_dataframe_query",
    "arguments": {
      "canvas_id": "<canvas_id>",
      "query": "<query>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired."
    },
    "query": {
      "type": "string",
      "description": "Read-only SQL SELECT statement. Reference tables by the names returned by fx_dataframe_describe or the table_name field from fx_get_timeseries. Example: SELECT date, rate FROM fx_usd_eur WHERE date > '2024-01-01' ORDER BY date"
    }
  },
  "required": [
    "canvas_id",
    "query"
  ],
  "additionalProperties": false
}

view source ↗

Resources

fx-currencies

All supported ISO 4217 currency codes with full names. Covers the ~30 ECB reference currencies.

uri fx://currencies mime application/json

fx-rates-latest

Latest exchange rates snapshot for a base currency as a stable URI. Returns all available quote currencies at the most recent ECB business-day fix.

uri fx://rates/latest/{base} mime application/json