AllRatesToday MCP Server — @allratestoday/mcp-server

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
📈 Historical series built in — 1d / 7d / 30d / 1y windows with sensible granularity per period
🧰 Six focused tools — get_exchange_rate, get_historical_rates, get_rates_authenticated, list_currencies, list_central_banks, get_official_rates; 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, 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, call get_official_rates: the latest table published by any of 121 central banks and 3 tax authorities (ECB, Fed, HMRC, US Treasury, Swiss BAZG, …), fixed once published and carrying the institution's own rate_date, no key needed. list_central_banks gives the codes. Dated tables and history sit behind the free key — see 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.
`list_central_banks`	✅	Codes, names and latest publication date of all 121 central banks + 3 tax authorities.
`get_official_rates`	✅	Latest official table (or one pair) published by any of them. A dated table needs the key.
`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.

Register at allratestoday.com/register — 30 seconds
Verify your email
Copy your key from the dashboard (format: art_live_xxxxx)
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.

☁️ Hosted endpoint — nothing to install

The same tools also run as a hosted Streamable HTTP MCP server (together with the tools of the sibling AllRatesToday server, nine in total). Paste the URL into any client that supports remote MCP — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI:

https://allratestoday.com/api/mcp

claude mcp add --transport http allratestoday https://allratestoday.com/api/mcp

Works keyless. With a key, send Authorization: Bearer art_live_… or, where the client only takes a URL, connect to https://allratestoday.com/api/mcp?api_key=art_live_…. Registry name: com.allratestoday/mcp. One-click Cursor / VS Code buttons: https://allratestoday.com/mcp/#hosted

📦 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 six 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:

Server starts — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting below).
Tools are listed — most clients have a "tools" or "MCP" panel showing the six tools.
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
list_central_banks — every covered central bank / tax authority with its code and latest publication date
get_official_rates — the official table (or one pair) a named institution published

get_historical_rates and get_rates_authenticated require ALLRATES_API_KEY; the other four work keyless.

`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
}

`list_central_banks`

Every official source the server can quote — 121 central banks plus HMRC, the US Treasury and Swiss BAZG — with the code that get_official_rates takes as bank, the institution's name, its latest publication date and a stale flag when it is behind its own schedule. Keyless.

Input — none.

Response (truncated):

{
  "sources": [
    { "code": "ecb", "name": "European Central Bank", "latest": "2026-09-30", "stale": false },
    { "code": "fed", "name": "Federal Reserve", "latest": "2026-09-29", "stale": false },
    "..."
  ],
  "stale_count": 0,
  "checked_at": "2026-10-01T09:00:00Z"
}

`get_official_rates`

The fixed, citable rate an institution published — for invoices, VAT and tax returns, customs, transfer pricing and audit. Not a live market rate.

Input:

Field	Type	Required	Description
`bank`	string	yes	Source code from `list_central_banks`, e.g. `ecb`, `fed`, `boe`, `rbi`, `hmrc`
`date`	string	no	`YYYY-MM-DD`. Omit for the latest table (keyless). Needs the API key. Weekends/holidays roll back to the last published date.
`source`	string	no	With `target`, narrows to one pair
`target`	string	no	With `source`, narrows to one pair

Response (one pair):

{
  "bank": "ecb",
  "rate_date": "2026-09-30",
  "source": "EUR",
  "target": "USD",
  "rate": 1.1355,
  "rate_type": "reference",
  "derived": false,
  "method": "published",
  "attribution": { "source": "Official rates published by ECB, served by AllRatesToday", "url": "https://allratestoday.com/central-bank-rates-api/ecb/", "terms": "Free to use with visible attribution linking to allratestoday.com" }
}

Omit source/target for the whole table as rates: [{ base, quote, type, value }]. Pairs the bank does not publish directly are cross-computed inside its own table and flagged derived: true. Always cite rate_date.

⚙️ 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
Every call returns "Invalid AllRatesToday API key"	Key is malformed (missing prefix, truncated, or revoked)	Copy a fresh key from the dashboard
Tools return "AllRatesToday API quota exceeded"	Monthly limit hit	Wait until next month or upgrade plan
Historical tool returns "Bad request"	Invalid period or unknown currency code	Period must be `1d`/`7d`/`30d`/`1y`; codes must be 3 letters
Server starts but tools never appear	Client didn't reload after config change	Fully quit (not just close) and reopen the client
`npx` runs but hangs forever	The server is waiting for an MCP client to connect — normal when run from a shell	Let your MCP client launch it

To inspect what the server is doing, run it manually with the key set:

ALLRATES_API_KEY=art_live_xxxxx npx -y @allratestoday/mcp-server

No output means healthy (stdio is reserved for the MCP protocol); errors print to stderr.

🛡️ Error reference

The server maps API errors to clear, actionable messages the assistant can relay to the user:

HTTP status	Meaning	Tool error message
200	Success	(rate returned)
400	Bad request — usually unknown currency code	`Bad request — possibly an unknown currency code`
401	Invalid or missing API key	`Invalid AllRatesToday API key`
429	Quota exceeded	`AllRatesToday API quota exceeded`
5xx	Server-side issue at allratestoday.com	`HTTP 5xx — <upstream message>`

❓ FAQ

Is the free plan really enough for normal use? Yes for personal/dev use. Heavy interactive use, multiple chat sessions per day, or production should consider the paid tiers.

Do you store my conversation or query data? No. Only your API key and the request parameters (source, target, period, time) are sent to allratestoday.com — never the LLM's conversation context.

What happens to my API key? It's only sent as a Bearer token in the Authorization header on requests to the AllRatesToday API. It's never logged or transmitted elsewhere.

Why is my first call slow? Cold-start of npx (first run downloads the package) plus the initial cache miss. Subsequent calls are typically <200ms.

Can I run this without npm/Node? Not currently — Node ≥18 is required. If a standalone binary matters to you, open an issue.

Is there a self-hosted option? Set ALLRATES_BASE_URL to your own AllRatesToday instance. Contact support@allratestoday.com for self-hosted licensing.

Does this work with ChatGPT? MCP works with any MCP-compatible client. ChatGPT Desktop has experimental MCP support; check OpenAI's docs for current status.

👩‍💻 Development

git clone https://github.com/cahthuranag/mcp-server.git
cd mcp-server
npm install
npm run build
ALLRATES_API_KEY=art_live_xxxxx node dist/index.js

The server runs on stdio and waits for an MCP client to connect; Ctrl+C to exit. npm run dev watches and rebuilds. To test against a local AllRatesToday instance:

ALLRATES_BASE_URL=http://localhost:8080/api ALLRATES_API_KEY=test_key node dist/index.js

Project structure

src/
├── index.ts      # MCP server, tool registration, request handlers
└── client.ts     # HTTP client for AllRatesToday API + error mapping
dist/             # Compiled JS (gitignored)
server.json       # MCP registry manifest

Contributing — issues and PRs welcome at github.com/cahthuranag/mcp-server. Before opening a PR: npm run build must succeed, test against a real API key, and update the tool descriptions in src/index.ts plus this README's tools reference if you change tool behavior.

📝 Changelog

See GitHub Releases for the full list. Recent highlights:

0.6.0 — Official rates: new keyless list_central_banks and get_official_rates tools expose the latest table from 121 central banks + 3 tax authorities (dated tables need the key)
0.5.0 — Keyless mode: the server starts and answers without an API key (get_exchange_rate via the open ECB reference table, list_currencies unchanged); metered tools return actionable sign-up guidance instead of the process exiting
0.4.x — README overhaul; registry metadata updates
0.3.x — API key required for all tools; fail-fast at startup with clear error
0.2.x — Removed news tool, required auth on get_historical_rates
0.1.x — Initial release with 5 tools

🔗 Links

API documentation · Interactive reference
Register (free) · Pricing
MCP protocol docs
GitHub · Bug reports
Support: support@allratestoday.com

📜 License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.github		.github
src		src
test		test
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
CURSOR-DIRECTORY-RULES.md		CURSOR-DIRECTORY-RULES.md
LICENSE		LICENSE
README-zh-CN.md		README-zh-CN.md
README.md		README.md
glama.json		glama.json
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

AllRatesToday MCP Server — @allratestoday/mcp-server

🚀 Why this server?

⚖️ Mid-market vs official central-bank rates

🔓 Keyless mode — what works with no setup

🔑 Get your API key (free)

🧩 Easiest install: the Claude Code plugin

☁️ Hosted endpoint — nothing to install

📦 Installation

🏁 Quick setup per client

Claude Code

Cursor

Claude Desktop

Windsurf

Generic stdio MCP client

✅ Verify it works

📚 Tools reference

`get_exchange_rate`

`get_historical_rates`

`get_rates_authenticated`

`list_currencies`

`list_central_banks`

`get_official_rates`

⚙️ Environment variables

💳 Plans

🛠️ Troubleshooting

🛡️ Error reference

❓ FAQ

👩‍💻 Development

📝 Changelog

🔗 Links

📜 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AllRatesToday MCP Server — @allratestoday/mcp-server

🚀 Why this server?

⚖️ Mid-market vs official central-bank rates

🔓 Keyless mode — what works with no setup

🔑 Get your API key (free)

🧩 Easiest install: the Claude Code plugin

☁️ Hosted endpoint — nothing to install

📦 Installation

🏁 Quick setup per client

Claude Code

Cursor

Claude Desktop

Windsurf

Generic stdio MCP client

✅ Verify it works

📚 Tools reference

get_exchange_rate

get_historical_rates

get_rates_authenticated

list_currencies

list_central_banks

get_official_rates

⚙️ Environment variables

💳 Plans

🛠️ Troubleshooting

🛡️ Error reference

❓ FAQ

👩‍💻 Development

📝 Changelog

🔗 Links

📜 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`get_exchange_rate`

`get_historical_rates`

`get_rates_authenticated`

`list_currencies`

`list_central_banks`

`get_official_rates`