Realtime Exchange Rate MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Realtime Exchange Rate MCP ServerWhat's the current USD to EUR rate?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/sdkandzod; 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.
Related MCP server: xe-mcp
🔑 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.
Register at allratestoday.com/register
Verify your email
Copy your key from the dashboard (format:
art_live_xxxxx)Use it as
ALLRATES_API_KEYin 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-mcpBoth 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_xxxxxRestart 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):
OS | Path |
macOS |
|
Windows |
|
Linux |
|
{
"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
Server starts — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting).
Tools are listed — most clients have a "tools" or "MCP" panel showing all four 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 produces a number without a tool call, the server is not connected.
📚 API reference
Tool | Purpose | Required input |
Current rate for one pair |
| |
Time series over a preset period |
| |
Multiple targets in one call, optional point-in-time |
| |
All supported codes, names, symbols | — |
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.
Field | Type | Required | Description |
| string (exactly 3 chars) | yes | ISO 4217 code, e.g. |
| string (exactly 3 chars) | yes | ISO 4217 code, e.g. |
{ "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.
Field | Type | Required | Description |
| string (exactly 3 chars) | yes | Source currency code |
| string (exactly 3 chars) | yes | Target currency code |
| string | no (default | One of |
Granularity per period:
| Granularity |
| Hourly |
| Daily |
| Daily |
| Weekly |
{ "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.
Field | Type | Required | Description |
| string (exactly 3 chars) | yes | Source currency code |
| string | yes | One or more codes, comma-separated ( |
| string (ISO 8601 date-time) | no | Historical point in time |
| string | no | One of |
{ "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
The source and target fields of get_exchange_rate and get_historical_rates are validated as exactly three characters, so pass ISO 4217 codes, not currency names.
⚙️ Environment variables
Variable | Default | Required | Purpose |
| — | yes | Your API key. The server exits with code 1 at startup if unset; sent as a |
|
| no | Override for a self-hosted or staging deployment. Trailing slashes are stripped. |
Set these in your MCP client's config (in the env block), not in your shell — MCP servers are launched as subprocesses with isolated environments.
🛡️ Error handling
Tool failures come back as an MCP tool result with isError: true. The text is AllRatesToday error (<status>): <message>, where <message> is the error field from the API response body when present, and HTTP <status> otherwise.
HTTP status | Meaning |
400 | Bad request — usually an unknown or malformed currency code |
401 | Invalid or missing API key |
429 | Rate limit or quota exceeded |
5xx | Server-side issue upstream |
Two errors are raised locally, before any HTTP call:
No API key at request time →
API key is required. Get one at https://allratestoday.com/register, then set ALLRATES_API_KEY in your MCP config.Unrecognised tool name →
Unknown tool: <name>
Because these arrive as text, the assistant relays them to the user — a 429 surfaces as "the API quota has been exceeded."
🛠️ Troubleshooting
Symptom | Likely cause | Fix |
Client shows "MCP server failed to start" or a red dot |
| Add the key to the |
Every call returns a 401 error | Key malformed, truncated, or revoked | Copy a fresh key from the dashboard |
Calls return a 429 error | Plan request limit hit | Wait for the quota to reset or upgrade the plan |
| Invalid period or unknown currency code |
|
Server starts but tools never appear | Client did not reload after the config change | Fully quit (not just close) and reopen the client |
| Normal — the server is waiting for an MCP client on stdio | 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-serverNo output means healthy — stdout is reserved for the MCP protocol; errors print to stderr.
💡 Notes
Do you store my conversation or query data? No. Only your API key and the request parameters (source, target, period, time, group) are sent to allratestoday.com — never the model's conversation context.
What happens to my API key? It is only sent as a Bearer token in the Authorization header on requests to the AllRatesToday API. The server does not log it.
Why is the first call slow? Cold start of npx (the first run downloads the package) plus an upstream cache miss.
Can I run this without npm/Node? Not currently — engines requires Node ≥ 18. If a standalone binary matters to you, open an issue.
Is there a self-hosted option? Point ALLRATES_BASE_URL at your own instance.
Does it work with other clients? Any MCP-compatible host with stdio transport works; the four clients above are simply the ones with documented config paths here.
👩💻 Development
git clone https://github.com/cahthuranag/realtime-exchange-rate-mcp.git
cd realtime-exchange-rate-mcp
npm install
npm run build
ALLRATES_API_KEY=art_live_xxxxx node dist/index.jsnpm run build runs tsc; npm run dev watches and rebuilds; npm start runs the compiled server. CI (.github/workflows/ci.yml) runs npm ci && npm run build on Node 22 for every push to main and every pull request.
To test against a local AllRatesToday instance:
ALLRATES_BASE_URL=http://localhost:8080/api ALLRATES_API_KEY=test_key node dist/index.jsProject structure:
src/
├── index.ts # MCP server, tool definitions, request handlers
└── client.ts # HTTP client for the AllRatesToday API + error mapping
dist/ # Compiled JS (gitignored)
server.json # MCP registry manifest
smithery.yaml # Smithery launch config
.mcp.json # Ready-to-copy client configIssues and PRs are welcome. Before opening a PR: npm run build must succeed, exercise the change against a real API key, and update both the tool descriptions in src/index.ts and the API reference above if tool behaviour changes.
📝 Changelog
See GitHub Releases for the full list. Recent highlights:
0.3.x — API key required for all tools; fail-fast at startup with clear instructions
0.2.x — Removed the news tool; required auth on
get_historical_rates0.1.x — Initial release with 5 tools
🔗 Links
Website: allratestoday.com
API docs: allratestoday.com/docs
Free API key: allratestoday.com/register
Status: allratestoday.com/status
Support: allratestoday.com/contact
MCP protocol: modelcontextprotocol.io
Bug reports: github.com/cahthuranag/realtime-exchange-rate-mcp/issues
📜 License
MIT — see LICENSE.
Available Tools
4 toolsget_exchange_rateA
Get the current mid-market exchange rate between two currencies. Returns a single rate number. Requires API key (ALLRATES_API_KEY).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ISO 4217 currency code (e.g. USD, EUR, GBP). | |
| target | Yes | ISO 4217 currency code (e.g. USD, EUR, GBP). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the tool returns a single rate number and requires an API key, which are key behaviors. It does not cover potential rate limits or error handling, but for a simple read operation, it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first explains purpose, second states requirement. No unnecessary words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 required parameters and no output schema, the description adequately states it returns a rate number and mentions API key requirement. No gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for both parameters (ISO 4217 currency codes). The description adds 'mid-market' context but does not enhance parameter semantics beyond what the schema already covers. With 100% schema description coverage, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the current mid-market exchange rate between two currencies. Returns a single rate number.' The verb 'Get' and resource 'exchange rate' are specific. It distinguishes from siblings like get_historical_rates (historical data) and list_currencies (list of codes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite: 'Requires API key (ALLRATES_API_KEY).' However, it does not explicitly state when to use this tool versus siblings like get_historical_rates or get_rates_authenticated, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_historical_ratesA
Get historical exchange-rate data points for a currency pair over a period. Periods: 1d (hourly), 7d (daily), 30d (daily), 1y (weekly). Requires API key (ALLRATES_API_KEY).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ISO 4217 currency code (e.g. USD, EUR, GBP). | |
| target | Yes | ISO 4217 currency code (e.g. USD, EUR, GBP). | |
| period | No | Time period to fetch history for. | 7d |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It reveals the API key requirement and period granularity (hourly, daily, weekly) but omits details on error handling, rate limits, or authentication failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the primary purpose, and efficiently covers period details and API key requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description covers the core purpose, period mapping, and authentication need. It does not describe the return format, but the information is sufficient for an agent to decide whether to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by mapping period values to granularity (1d=hourly, etc.), but for source/target it merely restates schema info. The addition is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get historical exchange-rate data points for a currency pair over a period,' clearly indicating the verb (get) and resource (historical exchange-rate data points). It distinguishes itself from siblings like get_exchange_rate (likely current rate) and list_currencies by focusing on historical data, though no explicit sibling differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for historical data over a period) and mentions a prerequisite (API key), but it does not specify when not to use it or mention alternative tools like get_exchange_rate for current rates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_rates_authenticatedA
Get rates with higher limits and multi-target support. Requires API key (ALLRATES_API_KEY). Supports comma-separated targets like "EUR,GBP,JPY".
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ISO 4217 currency code (e.g. USD, EUR, GBP). | |
| target | Yes | One or more target codes, comma-separated. | |
| time | No | Optional historical ISO 8601 timestamp. | |
| group | No | Optional grouping window. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the API key requirement and multi-target support, but lacks details on error handling, return format, or rate limits, providing only partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose and key feature (multi-target), with no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters, the description explains auth and target format but omits return value description, error scenarios, and usage of time/group parameters, leaving moderate gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds value by clarifying that the target parameter supports comma-separated codes with an example, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves rates with higher limits and multi-target support, distinguishing it from siblings like get_exchange_rate and get_historical_rates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions the requirement for an API key and implies use when higher limits or multiple targets are needed, but does not explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_currenciesA
List all supported currencies with code, name, and symbol. Requires API key (ALLRATES_API_KEY). Cached 24h upstream.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description compensates by noting authentication requirement and 24-hour caching, which are important behavioral traits not inferable from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no redundant information. Essential elements are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters (none), the description covers purpose, requirements, and caching. Could mention output format, but not critical for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description adds no parameter info, but baseline for no parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all supported currencies with specific attributes (code, name, symbol). It is distinct from sibling tools which deal with exchange rates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions API key requirement and caching, but does not specify when to use this tool versus alternative siblings like get_exchange_rate or get_historical_rates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.3.3- First observed
get_exchange_rate - First observed
get_historical_rates - First observed
get_rates_authenticated - First observed
list_currencies
TDQS
Scored across 4 tools
get_exchange_rate and get_rates_authenticated both provide current exchange rates, with the latter offering higher limits and multi-target support, causing potential confusion about which to use for single pair queries.
Most tools use a consistent 'get_' prefix, except list_currencies which uses 'list_'. The verb-noun pattern is clear, though get_rates_authenticated includes an adjective that slightly breaks the pattern.
With 4 tools covering current rate (single and multi-target), historical data, and currency listing, the count is well-scoped for an exchange rate server without unnecessary extras.
Core functionality is covered: current rates, historical data, and currency list. Missing features like amount conversion or specific date queries are minor gaps that don't significantly hinder workflows.
Maintenance
Related MCP Connectors
Live & historical FX rates and currency conversion for AI agents. No API keys.
Live & historical FX rates and currency conversion for AI agents. No API keys.
ExchangeRate MCP — wraps open.er-api.com (free, no auth)
Exchange MCP — wraps the Frankfurter currency exchange API (free, no auth)
Related MCP Servers
- FlicenseCqualityDmaintenanceEnables real-time currency exchange rate queries between any two currencies using ExchangeRate API, with automatic triggering by AI models through the MCP protocol.11-
- AlicenseAqualityBmaintenanceAn MCP server for the Xe Currency Data API that brings live FX rates, historical analysis, and quant-flavored tools into AI tools, working out of the box with zero credentials via Frankfurter/ECB data.12141MIT
- FlicenseNot gradedqualityCmaintenanceEnables currency conversion, exchange rates, geocoding, and weather queries through MCP tools, integrated with OpenAI Responses API.-
- AlicenseNot gradedqualityAmaintenanceConvert currencies, get FX rates, and query historical ECB exchange rate data via MCP.631Apache 2.0