Skip to main content
Glama
AllRatesToday MCP Server

AllRatesToday MCP Server

AllRatesToday MCP Server

npm version npm downloads License MCP

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

  • "List every supported currency."


Table of contents


Related MCP server: xe-mcp

What you get

Capability

Detail

Currencies

150+ ISO 4217 codes, all major and most exotics

Update frequency

Mid-market rates refresh every ~60 seconds

Data source

Tier-1 financial data providers (Reuters / Refinitiv-class)

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. A free key 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

If you forget, 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).

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

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

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.


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

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 AllRatesToday API key"

Key is malformed (missing prefix, truncated, or revoked)

Copy a fresh key from the dashboard

Tools return "AllRatesToday API quota exceeded"

Free-tier 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 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 AllRatesToday API key

429

Quota exceeded

AllRatesToday API quota exceeded

5xx

Server-side issue at allratestoday.com

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

Is the free plan really enough for normal use? Yes for personal/dev use. The free tier covers a few daily questions. Heavy interactive use, multiple chat sessions per day, or running the server in 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, 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 AllRatesToday 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 the initial AllRatesToday 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 your own AllRatesToday instance. Contact support@allratestoday.com for self-hosted licensing.

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/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. Hit Ctrl+C to exit.

To watch and rebuild on changes during development:

npm run dev

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
package.json      # npm metadata, dependencies, scripts

Contributing

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

  1. npm run build should succeed with no errors

  2. Test against a real AllRatesToday 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


License

MIT — see LICENSE.

Available Tools

9 tools
get_bank_ratesCommercial bank buy/sell board ratesA
Read-only
Inspect

Retail buy and sell rates a commercial bank displays on its own website (e.g. SBI's TT buying rate, an Emirates NBD or HSBC Hong Kong board), read hourly. Use for 'what rate does bank X give for USD today?', remittance comparisons between banks in one country, or rules that name a bank's card rate (India Income-tax Rule 115 uses SBI's TT buying rate). These are bank prices, NOT official or mid-market rates: for those use get_official_rates or get_exchange_rate. Give country alone for every covered bank there, or add bank for one board; ccy narrows one bank to a currency and date returns the stored board for a past day. Covers 1,200+ commercial banks in 120+ countries (ae, lk, in, pk, bd, np, vn, id, ph, am, az, ge, kz, tw, jp, kr, hk, cn, au, cz, pl, hu, tr, eg, za, ke, us); codes are listed at https://allratestoday.com/bank-exchange-rate-api/. Requires ALLRATES_API_KEY (the free key works).

Inputs: country (required), ccy, bank, date. Returns: buy, ccy, bank, name, +10 more

get_exchange_rateGet live exchange rateA
Read-only
Inspect

Use this when the user asks 'what is X in Y?', 'convert X to Y', 'current rate of EUR/USD', or any single fiat-to-fiat live exchange rate question. Returns the latest mid-market rate as a JSON object like { rate: 0.9234, source } meaning 1 source = 0.9234 target. Without an API key it answers from an official central-bank table instead (ECB first, else the bank that issues one of the two currencies) and says so in note — relay the rate_date; pairs no single bank publishes (or inverts) need a key. Does NOT support cryptocurrencies, commodities, or arithmetic on amounts. For multiple targets in one call use get_rates_authenticated; for a past date or fixed lookback (7d/30d/1y) use get_historical_rates.

Inputs: source (required), target (required). Returns: bank, note, rate, source, +2 more

get_historical_ratesGet historical rate time-seriesA
Read-only
Inspect

Use this for fixed-window time-series questions like 'how has EUR/USD moved this week', 'show me the last month of GBP/JPY', or 'chart 1-year history of AUD/USD'. Returns { source, target, period, data: [{ date, rate, timestamp }, ...] } — sampling is fixed per period (1d=hourly, 7d/30d=daily, 1y=weekly) and the window always ends NOW. Needs an API key on a paid plan; free and trial keys get a 403. For a specific past datetime use get_rates_authenticated with time. For a single live rate use get_exchange_rate.

Inputs: source (required), target (required), period. Returns: data, period, source, target, +1 more

get_official_ratesGet a bank's official published ratesA
Read-only
Inspect

OFFICIAL rates a named institution published — 'what is the ECB rate for USD?', 'Bank of Japan rate today', 'HMRC rate for invoicing'. These are the fixed, citable rates for compliance, tax, customs and accounting — NOT live market rates (use get_exchange_rate for those). Omit date for the newest published table (no API key needed); give date (API key, paid plan) for the table in force that day — weekends/holidays roll back to the last published date and the response's rate_date says which. Omit source/target for the full table; give both for one pair — cross-computed inside the bank's own table when not directly published, flagged derived. Always cite the returned rate_date.

Inputs: bank (required), date, source, target. Returns: bank, rate, rates, stale, +6 more

get_rates_authenticatedGet multi-target or point-in-time ratesA
Read-only
Inspect

Use this for (a) one source against multiple targets in a single call ('USD vs EUR, GBP, JPY'), or (b) the rate at a specific past datetime ('EUR/USD at 2025-03-14T12:00Z'), optionally bucketed by hour/day/week/month. Returns { rates: [{ rate, source, target, time }, ...] } — one row per target × time bucket. Multi-target latest rates work on any key; a past datetime (time) needs a paid plan. For a single live pair use get_exchange_rate. For fixed lookback windows (1d/7d/30d/1y ending now) use get_historical_rates.

Inputs: source (required), target (required), time, group. Returns: rates

get_reference_rateGet the Daily Reference Rate (16:00 London)A
Read-only
Inspect

AllRatesToday's once-a-day, never-revised mid-market rate: the per-currency median of samples in a five-minute window centred on 16:00 London, published each business day. Use it when the user needs ONE reproducible rate per day — index levels, return series, research datasets, month-end reports — rather than a live quote (get_exchange_rate) or an institution's official rate (get_official_rates). Omit source/target for the whole table; give both for one pair (crossed via USD, flagged derived). Omit date for the latest table (no key needed); give date (API key, paid plan) for a past business day. Not the WM/Refinitiv fix and not a registered benchmark — relay the disclaimer and the rate_date.

Inputs: date, source, target. Returns: base, rate, time, rates, +6 more

list_central_banksList covered central banks & tax authoritiesA
Read-only
Inspect

Call this FIRST when you need a bank code, or for 'which central banks do you cover?' / 'do you have rates from X?'. Returns every covered source — 130+ central banks and tax authorities (HMRC, US Treasury, Swiss BAZG, India CBIC, Peru SUNAT) — with code (what get_official_rates takes as bank), name, latest publication date and whether it is behind schedule. No API key needed.

Inputs: no named parameters. Returns: sources, checked_at, stale_count

list_currenciesList supported currenciesA
Read-only
Inspect

Call this BEFORE other tools when you are unsure whether a currency code is supported, or when the user asks 'what currencies do you support?', 'is X a valid currency?', or 'what is the symbol for X?'. Returns { currencies: [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...], count } covering 160+ ISO 4217 fiat currencies. Does NOT include cryptocurrencies. Cheap to call (cached 24h upstream) — use it to validate user input and prevent downstream errors in get_exchange_rate / get_rates_authenticated / get_historical_rates.

Inputs: no named parameters. Returns: count, currencies

request_trial_keyRequest a trial API keyAInspect

Self-issue an AllRatesToday API key with 100 lifetime calls, valid 7 days, with no account and no email. Use it when another tool answered "needs an API key" and the user wants real-time rates or history right now. The key is adopted by this server for the rest of the session and returned once — tell the user to put it in the MCP config as ALLRATES_API_KEY to keep it. Capped at 3 keys per IP per day. For a lasting key, register at https://allratestoday.com/register (free) or see https://allratestoday.com/pricing.

Inputs: agent, purpose. Returns: key, note, calls, adopted, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 9 tools

    Disambiguation3/5

    The descriptions do heavy lifting with explicit 'use X instead' guidance, but three tools (get_exchange_rate, get_rates_authenticated, get_historical_rates) all answer 'what is the rate at/over time T' and differ mainly by cardinality, auth tier and window shape rather than by domain. The rate-concept family is even wider once get_official_rates and get_reference_rate are added, so an agent must read carefully to avoid picking a live quote when a citable official or daily-fixed rate was wanted.

    Naming Consistency4/5

    Consistent snake_case verb_noun across the set: get_*_rates, list_central_banks, list_currencies, request_trial_key. The one deviation is get_rates_authenticated, where the qualifier is an auth attribute rather than a resource noun, which makes it read like a variant of the other rate tools instead of a multi-target/point-in-time operation.

    Tool Count5/5

    Nine tools is well within a healthy scope for a rates API, and each maps to a distinct capability (live, historical, official, bank, reference, two enumerations, key issuance). Nothing appears redundant enough to drop.

    Completeness4/5

    Coverage is strong across the rate lifecycle: live quotes, fixed-window history, point-in-time, official/institutional, retail bank and a reproducible daily fix, plus currency and central-bank enumeration and self-service key issuance. The notable gap is that get_bank_rates needs a bank code for 1,200+ banks but there is no list_banks tool (codes are pushed to an external URL), and amount conversion is explicitly unsupported, forcing the agent to do arithmetic itself.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Real-time currency exchange rates and crypto prices via MCP. Convert between 60+ fiat currencies and 30+ cryptocurrencies with multi-source failover. No API keys needed for upstream data.
      ISC
    • A
      license
      A
      quality
      C
      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
      7 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Read-only tools for published currency buy and sell quotes from more than 40 Uruguayan exchange houses and banks, rate comparisons, conversion, historical data, and economic news. Open-source TypeScript server with stdio and remote HTTP transports; no API key required.
      7
      4 npm
      9
      MIT