Realtime Exchange Rate MCP Server


   

English | 简体中文

Give your AI coding assistant a live window into the foreign-exchange market.

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 data, and multi-currency lookups.

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

---

Table of contents

• What you get
• Get an API key (required)
• Install
• Quick setup per client
• Claude Code
• Cursor
• Claude Desktop
• Windsurf
• Generic stdio MCP client
• Verify it works
• Tools reference
• Environment variables
• Troubleshooting
• Error reference
• FAQ
• Development
• Changelog
• Support
• License

---

What you get

| Capability | Detail | |---|---| | Currencies | 150+ ISO 4217 codes, all major and most exotics | | Update frequency | Mid-market rates refresh every ~60 seconds | | Historical depth | Up to 1 year via 1d / 7d / 30d / 1y granularity | | Tools exposed | 4 — get_exchange_rate, get_historical_rates, get_rates_authenticated, list_currencies | | Transport | stdio (subprocess), MCP 1.x compatible | | Runtime | Node.js ≥18 |

---

Get an API key (required)

The server will not start without a valid ALLRATES_API_KEY. Rates are served by AllRatesToday; 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 clear registration instructions on stderr and exits with code 1.

---

Install

The server is published as an npm package. 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 directly 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:

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

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. If the MCP integration shows a red dot or "failed to connect", the API key is missing or wrong (see Troubleshooting).

1. Tools are listed — most clients have a "tools" or "MCP" panel. You should see:

• get_exchange_rate
• get_historical_rates
• get_rates_authenticated
• list_currencies

1. A live call returns a number — ask the assistant:

What's the current USD to EUR rate?

The assistant will call get_exchange_rate(source: "USD", target: "EUR") and reply with a real rate (e.g. "USD to EUR is currently 0.9214."). If it fabricates a number without making a tool call, the server isn't connected.

---

Tools reference

All four tools require an 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" }

Example 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" }

Example 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" }

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

Input — none.

Example 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 | — | yes | Your API key. The server exits at startup if unset. | | ALLRATES_BASE_URL | https://allratestoday.com/api | no | Override for self-hosted or staging deployments. |

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

---

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Client shows "MCP server failed to start" or red dot | ALLRATES_API_KEY not set or invalid | Verify the key in your client config; check it matches the dashboard | | Tools show but every call returns "Invalid API key" | Key is malformed (missing prefix, truncated, or revoked) | Copy a fresh key from the dashboard | | Tools return "API quota exceeded" | Plan request 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 in client | 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 — this is normal when run from a shell | Don't run from a shell; let your MCP client launch it |

Inspect server logs

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

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

You should see no output when healthy (stdio is reserved for the MCP protocol). Any errors print to stderr.

---

Error reference

The server maps API errors to clear, actionable messages.

| 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 API key | | 429 | Quota exceeded | API quota exceeded | | 5xx | Upstream server-side issue | HTTP 5xx — <upstream message> |

The LLM will surface these messages in its response, so a user prompt that hits a 429 results in the assistant saying "the API quota has been exceeded — please try again next month or upgrade your plan."

---

FAQ

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

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

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

Can I run this without npm/Node? Not currently — Node ≥18 is required. We've considered a standalone binary; if that matters to you, open an issue.

Is there a self-hosted option? Yes, set ALLRATES_BASE_URL to point to your own instance.

Does this work with ChatGPT? The Anthropic MCP standard 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/realtime-exchange-rate-mcp.git
cd realtime-exchange-rate-mcp
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. Hit Ctrl+C to exit.

To watch and rebuild on changes during development:

npm run dev

To test against a local 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 + error mapping
dist/             # Compiled JS (gitignored)
server.json       # MCP registry manifest
package.json      # npm metadata, dependencies, scripts

Contributing

Issues and PRs welcome at github.com/cahthuranag/realtime-exchange-rate-mcp. Before opening a PR:

1. npm run build should succeed with no errors
2. Test against a real API key (set in ALLRATES_API_KEY)
3. Update tool descriptions in src/index.ts if you change tool behavior
4. Update this README's "Tools reference" section if you add or rename a tool

---

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 error
• 0.2.x — Removed news tool, required auth on get_historical_rates
• 0.1.x — Initial release with 5 tools

---

Support

• Bug reports: github.com/cahthuranag/realtime-exchange-rate-mcp/issues
• MCP questions: modelcontextprotocol.io — protocol docs

---

License

MIT — see LICENSE.