AllRatesToday MCP Server — @allratestoday/mcp-server

English | 简体中文

Give your AI assistant a live window into the foreign-exchange market. A Model Context Protocol server that lets Claude Code, Cursor, Claude Desktop, Windsurf, and any MCP-compatible client fetch real-time currency rates, historical series, and multi-currency lookups from the AllRatesToday API.

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."

🚀 Why this server?

• 📡 Live mid-market rates — 150+ ISO 4217 currencies, refreshed every ~60 seconds from institutional interbank data
• 📈 Historical series built in — 1d / 7d / 30d / 1y windows with sensible granularity per period
• 🧰 Four focused tools — get_exchange_rate, get_historical_rates, get_rates_authenticated, list_currencies; small surface, easy for the model to use correctly
• 🔌 Works everywhere MCP does — stdio transport, MCP 1.x; Claude Code, Cursor, Claude Desktop, Windsurf, or any generic host
• 🔓 Works with no API key — installs and answers out of the box from the open ECB reference table; a free key unlocks real-time rates for 160+ currencies
• 🛡️ Honest about what it returned — every keyless answer says which rate it is and when it was published; API errors map to clear, actionable messages
• 🔒 Nothing leaks — only the request parameters and your API key ever reach allratestoday.com; never conversation context

⚖️ Mid-market vs official central-bank rates

Everything this server returns is a mid-market rate: the live interbank midpoint, refreshed every ~60 seconds — the right number for price display, conversion, and anything that should track the market. It is not the official rate a tax authority or auditor may require. For those, AllRatesToday also serves published central-bank and tax-authority rates (100+ sources — ECB, Fed, HMRC, US Treasury, …) that are fixed once published and carry the institution's own publication date — via the central bank REST API and per-bank npm SDKs. The two can diverge by several percent, so pick by use case, not convenience.

🔓 Keyless mode — what works with no setup

Install it with no configuration at all and it starts, connects, and answers:

| Tool | Keyless | What you get | |---|---|---| | get_exchange_rate | ✅ | Official ECB daily reference rate, ~30 major currencies. The response carries rate_date and a note saying so, so the assistant never passes it off as a live quote. | | list_currencies | ✅ | All 160+ supported ISO 4217 codes. | | get_historical_rates | 🔑 | Returns one sentence explaining how to get a free key. | | get_rates_authenticated | 🔑 | Same. |

The keyless path reads the open, edge-cached /api/open/central-bank/ecb endpoint — no upstream cost, no rate limit to trip over, nothing to sign up for.

🔑 Get your API key (free)

A key unlocks real-time mid-market rates across 160+ currencies, historical series, and multi-target / point-in-time lookups. The free tier is enough for development and personal use — no credit card required.

1. Register at allratestoday.com/register — 30 seconds
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

Without one the server prints a short summary of keyless mode on stderr and keeps running — it never exits, because an MCP server that exits breaks the host client's whole configuration.

🧩 Easiest install: the Claude Code plugin

If you use Claude Code, install the plugin instead of configuring this server by hand — it bundles both AllRatesToday MCP servers, two skills, and five slash commands (/rate, /convert, /official-rate, /fx-history, /add-currency-support):

/plugin marketplace add AllRates-Today/claude-code-plugin
/plugin install allratestoday@allratestoday

Everything below still applies for other MCP clients.

📦 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're not meant to be run interactively from your shell; your MCP client launches them as a subprocess.

🏁 Quick setup per client

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. Verify by asking it: "What's the current USD to EUR rate?"

Cursor

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

{
  "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):

| OS | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

{
  "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 the environment variable ALLRATES_API_KEY set. The protocol version is MCP 1.x.

✅ Verify it works

After configuring your client, test in this order:

1. Server starts — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting below).
2. Tools are listed — most clients have a "tools" or "MCP" panel showing the 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 fabricates a number without a tool call, the server isn't connected.

📚 Tools reference

• get_exchange_rate — current rate for one pair
• get_historical_rates — time series over a preset period
• get_rates_authenticated — multiple targets in one call, optional point-in-time
• list_currencies — all supported currency codes, names, symbols

All four tools require ALLRATES_API_KEY.

---

get_exchange_rate

Current mid-market rate between two currencies.

Input

| Field | Type | Required | Description | |---|---|---|---| | source | string | yes | 3-letter ISO 4217 code, e.g. USD | | target | string | yes | 3-letter ISO 4217 code, e.g. EUR |

Example call

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

Response:

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

get_historical_rates

Time-series data points for a currency pair over a fixed period.

Input

| Field | Type | Required | Description | |---|---|---|---| | source | string | yes | Source currency code | | target | string | yes | Target currency code | | period | string | no (default 7d) | One of 1d, 7d, 30d, 1y |

Granularity by period

| period | Data points | |---|---| | 1d | Hourly (24 points) | | 7d | Daily (7 points) | | 30d | Daily (30 points) | | 1y | Weekly (52 points) |

Example call

{ "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 optional historical timestamp or grouping window.

Input

| Field | Type | Required | Description | |---|---|---|---| | source | string | yes | Source currency code | | target | string | yes | One or more codes, comma-separated (EUR,GBP,JPY) | | time | string (ISO 8601) | no | Historical point in time | | group | string | no | One of hour, day, week, month |

Example call

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

Response:

[
  { "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. Cached upstream for 24 hours — 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
}

---

⚙️ Environment variables

| Variable | Default | Required | Purpose | |---|---|---|---| | ALLRATES_API_KEY | — | no | Your API key. Unset ⇒ keyless mode (see above); set ⇒ real-time rates and the historical tools. | | ALLRATES_BASE_URL | https://allratestoday.com/api | no | Override for self-hosted or staging deployments. |

Set these in your MCP client's config (in the env block) — not in your shell — because MCP servers are launched as subprocesses with isolated environments.

💳 Plans

A free tier and paid plans are available — see allratestoday.com/pricing for current quotas. All plans include the same currency coverage and historical depth; only the request quotas differ.

🛠️ Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Client shows "MCP server failed to start" or red dot | Not a missing key — 0.5.0+ starts fine without one. Usually npx cannot reach the registry, or Node is older than 18 | Run npx -y @allratestoday/mcp-server in a shell and read stderr | | Rates look like yesterday's, response mentions "keyless mode" | No key set, so answers come from the ECB daily reference table | Set ALLRATES_API_KEY for real-time mid-market rates