Skip to main content
Glama
AllRates-Today

Realtime Exchange Rate MCP Server

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.

Powered by AllRatesToday npm version npm downloads CI MCP TypeScript License

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 in1d (hourly), 7d (daily), 30d (daily), 1y (weekly)

  • 🧰 Four focused toolsget_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.

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.

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

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

Tool

Purpose

Required input

get_exchange_rate

Current rate for one pair

source, target

get_historical_rates

Time series over a preset period

source, target

get_rates_authenticated

Multiple targets in one call, optional point-in-time

source, target

list_currencies

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

source

string (exactly 3 chars)

yes

ISO 4217 code, e.g. USD

target

string (exactly 3 chars)

yes

ISO 4217 code, e.g. EUR

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

source

string (exactly 3 chars)

yes

Source currency code

target

string (exactly 3 chars)

yes

Target currency code

period

string

no (default 7d)

One of 1d, 7d, 30d, 1y

Granularity per period:

period

Granularity

1d

Hourly

7d

Daily

30d

Daily

1y

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

source

string (exactly 3 chars)

yes

Source currency code

target

string

yes

One or more codes, comma-separated (EUR,GBP,JPY)

time

string (ISO 8601 date-time)

no

Historical point in time

group

string

no

One of hour, day, week, month

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

ALLRATES_API_KEY

yes

Your API key. The server exits with code 1 at startup if unset; sent as a Bearer token in the Authorization header.

ALLRATES_BASE_URL

https://allratestoday.com/api

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

ALLRATES_API_KEY not set

Add the key to the env block in your client config

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

get_historical_rates returns a 400 error

Invalid period or unknown currency code

period must be 1d/7d/30d/1y; codes must be exactly 3 letters

Server starts but tools never appear

Client did not reload after the config change

Fully quit (not just close) and reopen the client

npx runs but hangs forever

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-server

No 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.js

npm 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.js

Project 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 config

Issues 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_rates

  • 0.1.x — Initial release with 5 tools

📜 License

MIT — see LICENSE.

Available Tools

4 tools
get_exchange_rateA

Get the current mid-market exchange rate between two currencies. Returns a single rate number. Requires API key (ALLRATES_API_KEY).

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesISO 4217 currency code (e.g. USD, EUR, GBP).
targetYesISO 4217 currency code (e.g. USD, EUR, GBP).

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesISO 4217 currency code (e.g. USD, EUR, GBP).
targetYesISO 4217 currency code (e.g. USD, EUR, GBP).
periodNoTime period to fetch history for.7d

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesISO 4217 currency code (e.g. USD, EUR, GBP).
targetYesOne or more target codes, comma-separated.
timeNoOptional historical ISO 8601 timestamp.
groupNoOptional grouping window.

TDQS

A4.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv0.3.3
    • First observedget_exchange_rate
    • First observedget_historical_rates
    • First observedget_rates_authenticated
    • First observedlist_currencies

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    C
    quality
    D
    maintenance
    Enables real-time currency exchange rate queries between any two currencies using ExchangeRate API, with automatic triggering by AI models through the MCP protocol.
    1
    1
    -
  • A
    license
    A
    quality
    B
    maintenance
    An 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.
    12
    14
    1
    MIT