Realtime Exchange Rate MCP Server — @allratestoday/mcp-server

A Model Context Protocol server that lets Claude Code, Cursor, Claude Desktop, Windsurf, and any other MCP-compatible client fetch real-time currency rates, historical series, and multi-currency lookups from the AllRatesToday API. Rates come from institutional interbank market data.

English | 简体中文

After installation, your assistant can answer questions like:

• "What's the current USD to EUR rate?"
• "Show me how GBP/JPY moved over the last 30 days."
• "Convert 250 USD into CAD at a real rate."
• "Compare USD against EUR, GBP, and JPY simultaneously."
• "List every supported currency."

🚀 Features

• 💱 Live mid-market rates — current rate for any supported ISO 4217 pair
• 📈 Historical series built in — 1d (hourly), 7d (daily), 30d (daily), 1y (weekly)
• 🧰 Four focused tools — get_exchange_rate, get_historical_rates, get_rates_authenticated, list_currencies; a small surface the model uses correctly
• 🔌 Works everywhere MCP does — stdio transport, MCP SDK 1.x; Claude Code, Cursor, Claude Desktop, Windsurf, or any generic stdio host
• 🛡️ Fail-fast and honest — refuses to start without an API key and relays upstream API errors verbatim instead of guessing
• 🔒 Nothing leaks — only the request parameters and your API key ever reach allratestoday.com; never conversation context
• 📦 Two runtime dependencies — @modelcontextprotocol/sdk and zod; Node.js ≥ 18

Everything these tools return is a mid-market rate — the interbank midpoint, the right number for price display and conversion. It is not the official rate a tax authority or auditor may require; for published central-bank and tax-authority rates, see the AllRatesToday docs.

🔑 Get your API key

The server will not start without a valid ALLRATES_API_KEY, and all four tools require it. A free key is enough for development and personal use.

1. Register at allratestoday.com/register
2. Verify your email
3. Copy your key from the dashboard (format: art_live_xxxxx)
4. Use it as ALLRATES_API_KEY in the configs below

If the key is missing, the server prints registration instructions on stderr and exits with code 1.

📦 Installation

The simplest install is zero-install via npx, which is what every config below uses:

# Run without installing (recommended)
npx -y @allratestoday/mcp-server

# Or install globally
npm install -g @allratestoday/mcp-server
allratestoday-mcp

Both commands launch the stdio MCP server and wait for a client to connect — they are not meant to be run interactively from your shell; your MCP client launches them as a subprocess.

🏁 Quick start

Each client reads MCP servers from a different config file. Pick yours below.

Claude Code

The fastest path uses the built-in CLI:

claude mcp add allratestoday -- npx -y @allratestoday/mcp-server
claude mcp env allratestoday ALLRATES_API_KEY=art_live_xxxxx

Restart Claude Code, then ask: "What's the current USD to EUR rate?"

Cursor

Edit ~/.cursor/mcp.json (or .cursor/mcp.json inside your project for a project-scoped server):

{
  "mcpServers": {
    "allratestoday": {
      "command": "npx",
      "args": ["-y", "@allratestoday/mcp-server"],
      "env": {
        "ALLRATES_API_KEY": "art_live_xxxxx"
      }
    }
  }
}

Restart Cursor. The four tools should appear in the MCP tool picker.

Claude Desktop

Edit the config file (path depends on OS):

{
  "mcpServers": {
    "allratestoday": {
      "command": "npx",
      "args": ["-y", "@allratestoday/mcp-server"],
      "env": {
        "ALLRATES_API_KEY": "art_live_xxxxx"
      }
    }
  }
}

Fully quit and reopen Claude Desktop (Cmd+Q on macOS, right-click tray icon → Exit on Windows). Closing the window alone keeps the old config loaded.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json with the same mcpServers block as above, then restart Windsurf.

Generic stdio MCP client

Any MCP host that supports stdio transport works. The launch command is:

npx -y @allratestoday/mcp-server

…with ALLRATES_API_KEY set in the subprocess environment. The same block, ready to copy, also lives in .mcp.json in this repo; smithery.yaml describes the same stdio launch for Smithery, and server.json is the MCP registry manifest.

Verify it works

1. Server starts — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting).
2. Tools are listed — most clients have a "tools" or "MCP" panel showing all four tools.
3. A live call returns a number — ask "What's the current USD to EUR rate?" The assistant should call get_exchange_rate(source: "USD", target: "EUR") and reply with a real rate. If it produces a number without a tool call, the server is not connected.

📚 API reference

All four tools require ALLRATES_API_KEY, and every input schema sets additionalProperties: false — unknown fields are rejected.

get_exchange_rate

Current mid-market rate between two currencies. Calls GET /rate.

{ "source": "USD", "target": "EUR" }

Response shape — rate (number) and source (string, the upstream data source identifier):

{ "rate": 0.92145, "source": "..." }

get_historical_rates

Time-series data points for a currency pair over a fixed period. Calls GET /historical-rates.

Granularity per period:

{ "source": "USD", "target": "INR", "period": "30d" }

Response (truncated):

{
  "source": "USD",
  "target": "INR",
  "period": "30d",
  "data": [
    { "date": "2026-03-27T00:00:00Z", "rate": 83.42, "timestamp": 1743033600000 },
    { "date": "2026-03-28T00:00:00Z", "rate": 83.51, "timestamp": 1743120000000 },
    "..."
  ]
}

get_rates_authenticated

Multiple targets in one call, with an optional historical timestamp or grouping window. Calls GET /v1/rates.

{ "source": "USD", "target": "EUR,GBP,JPY" }

Response — an array of { rate, source, target, time }:

[
  { "rate": 0.9214, "source": "USD", "target": "EUR", "time": "2026-04-26T11:00:00Z" },
  { "rate": 0.7891, "source": "USD", "target": "GBP", "time": "2026-04-26T11:00:00Z" },
  { "rate": 151.34, "source": "USD", "target": "JPY", "time": "2026-04-26T11:00:00Z" }
]

list_currencies

All supported currencies with codes, names, and symbols. Calls GET /v1/symbols, cached 24 h upstream — cheap to call for validating user input before the other tools.

Input — none.

Response (truncated):

{
  "currencies": [
    { "code": "USD", "name": "US Dollar", "symbol": "$" },
    { "code": "EUR", "name": "Euro", "symbol": "€" },
    { "code": "GBP", "name": "British Pound", "symbol": "£" },
    "..."
  ],
  "count": 162
}

🗺️ Currencies covered

Every currency the AllRatesToday API serves is available through these tools — call list_currencies for the authoritative live list. Commonly used codes include:

🇺🇸 USD · 🇪🇺 EUR · 🇬🇧 GBP · 🇯🇵 JPY · 🇨🇦 CAD · 🇮🇳 INR