Realtime Exchange Rate Mcp

实时汇率 MCP 服务 — @allratestoday/mcp-server

一个模型上下文协议服务，可让 Claude Code、Cursor、Claude Desktop、Windsurf 及其他兼容 MCP 的客户端从 AllRatesToday API 获取实时汇率、历史走势和多币种查询结果。汇率为中间市场汇率，不含零售点差。

English | 简体中文

安装后，你的助手可以回答这类问题：

• “当前 USD 对 EUR 的汇率是多少？”
• “给我看看 GBP/JPY 过去 30 天的走势。”
• “按实时汇率将 250 USD 换算成 CAD。”
• “同时比较 USD 对 EUR、GBP 和 JPY 的汇率。”
• “列出所有受支持的货币。”
• “今天 USD 的 ECB 官方汇率是多少？”

本 README 介绍 npm 软件包 @allratestoday/mcp-server（当前版本为 0.7.6）。其源代码位于 AllRates-Today/mcp-server。

🚀 功能

• 💱 实时中间市场汇率 — 任意受支持的 ISO 4217 货币对的当前汇率
• 📈 内置历史走势 — 1d（每小时）、7d（每天）、30d（每天）、1y（每周）
• 🧰 八种专用工具 — get_exchange_rate、get_historical_rates、get_rates_authenticated、list_currencies、list_central_banks、get_official_rates、get_reference_rate、request_trial_key；工具范围精简，模型能够正确使用（托管端点 https://allratestoday.com/api/mcp 列出 11 种工具：上述工具以及 get_official_rate_history、compare_official_rates、get_publication_calendar）
• 🏛️ 官方汇率 — 来自 121 家中央银行和 3 家税务机构的最新汇率表，无需密钥
• 🔌 适用于所有支持 MCP 的场景 — stdio 传输、MCP SDK 1.x；支持 Claude Code、Cursor、Claude Desktop、Windsurf 或任何通用 stdio 宿主
• 🔓 无需 API 密钥即可使用 — 以无密钥模式启动，不会因缺少密钥而退出；无密钥模式的答复会说明所依据的官方汇率表及其 rate_date
• 🛡️ 如实报告错误 — 转达上游 API 错误，而非猜测；需要密钥的工具会说明如何获取密钥
• 🔒 不会泄露信息 — 只有请求参数和你的 API 密钥会发送至 allratestoday.com；绝不会发送对话上下文
• 📦 仅有两个运行时依赖 — @modelcontextprotocol/sdk 和 zod；Node.js ≥ 18

配置密钥后，get_exchange_rate、get_historical_rates 和 get_rates_authenticated 会返回中间市场汇率，适用于价格展示和换算。这并非税务机构或审计人员可能要求的官方汇率；如需官方汇率，请使用 get_official_rates（来自 121 家中央银行和 3 家税务机构的最新已发布汇率表，无需密钥），或参阅 AllRatesToday 文档。

🔑 获取 API 密钥

密钥可选。没有 ALLRATES_API_KEY 时，服务会以无密钥模式启动：

工具	无密钥模式	可获取内容
get_exchange_rate	✅	官方央行汇率：优先使用 ECB 表格；否则使用发行目标货币或源货币的央行汇率（例如，USD/GBP → Bank of England）。只有央行发布的货币对，或其反向货币对（标记为 derived: true），才能在无密钥模式下使用
list_currencies	✅	全部 160+ 种受支持的货币代码
list_central_banks	✅	全部 121 家央行和 3 个税务机关的代码及最新发布日期
get_official_rates	✅	最新官方表格（或单个货币对）；查询指定日期的表格需要付费套餐密钥
get_reference_rate	✅	最新 Daily Reference Rate 表格（伦敦时间 16:00）；查询过去日期需要付费套餐密钥
request_trial_key	✅	无需账户即可签发一个可调用 100 次、有效期 7 天的密钥，并在当前会话中启用该密钥
get_historical_rates	🔑	需要付费套餐密钥（免费密钥和试用密钥会返回 403）
get_rates_authenticated	🔑	使用免费密钥可查询最新汇率；指定 time（过去的日期时间）需要付费套餐

免费密钥可解锁 160+ 种货币的实时中间价汇率和多目标查询。所有历史汇率和指定日期的汇率——中间价历史、指定时点查询、指定日期的官方汇率表及参考汇率表——都需要付费套餐；免费密钥和试用密钥会返回 403 historical_requires_paid_plan（定价）。

1. 在 allratestoday.com/register 注册
2. 验证电子邮箱
3. 从控制面板复制密钥（格式：art_live_xxxxx）
4. 在下方配置中将其用作 ALLRATES_API_KEY

如果未提供密钥，服务会在 stderr 输出简短的无密钥模式摘要并继续运行——不会因缺少密钥而退出。

📦 安装

最简单的安装方式是通过 npx 零安装，下方所有配置均使用这种方式：

# Run without installing (recommended)
npx -y @allratestoday/mcp-server

# Or install globally
npm install -g @allratestoday/mcp-server
allratestoday-mcp

这两条命令都会启动 stdio MCP 服务并等待客户端连接——它们不是供你在 Shell 中交互式运行的；MCP 客户端会将其作为子进程启动。

🏁 快速开始

每个客户端都从不同的配置文件读取 MCP 服务。请在下方选择对应的客户端。

Claude Code

最快的方式是使用内置 CLI：

claude mcp add allratestoday -- npx -y @allratestoday/mcp-server
claude mcp env allratestoday ALLRATES_API_KEY=art_live_xxxxx

重启 Claude Code，然后询问：“当前 USD 兑 EUR 的汇率是多少？”

Cursor

编辑 ~/.cursor/mcp.json（如果要配置项目级服务，则编辑项目内的 .cursor/mcp.json）：

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

重启 Cursor。MCP 工具选择器中应该会显示这八个工具。

Claude Desktop

编辑配置文件（路径因操作系统而异）：

操作系统	路径
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"
      }
    }
  }
}

完全退出并重新打开 Claude Desktop（macOS 上按 Cmd+Q；Windows 上右键点击托盘图标 → 退出）。仅关闭窗口不会卸载旧配置。

Windsurf

使用与上方相同的 mcpServers 配置块编辑 ~/.codeium/windsurf/mcp_config.json，然后重启 Windsurf。

通用 stdio MCP 客户端

任何支持 stdio 传输的 MCP 主机均可使用。启动命令如下：

npx -y @allratestoday/mcp-server

……也可以在子进程环境中设置 ALLRATES_API_KEY。本仓库的 .mcp.json 中也有可直接复制的相同配置块；smithery.yaml 描述了用于 Smithery 的相同 stdio 启动方式，而 server.json 则是 MCP 注册表清单。

验证是否正常工作

1. 服务已启动 — 打开客户端。无论是否提供密钥，服务都会启动，因此如果看到红点或“连接失败”，表示客户端无法启动服务 — 通常是因为 npx 或 Node 版本低于 18（参见故障排除）。
2. 已列出工具 — 大多数客户端都有一个“工具”或“MCP”面板，其中会显示全部 8 个工具。
3. 实时调用返回数字 — 询问 “当前 USD 兑 EUR 的汇率是多少？” 助手应调用 get_exchange_rate(source: "USD", target: "EUR")，并回复真实汇率。如果它没有调用工具就给出数字，则说明服务未连接。

📚 API 参考

工具	用途	必需输入
get_exchange_rate	一个货币对的当前汇率	source、target
get_historical_rates	预设期间内的时间序列	source、target
get_rates_authenticated	一次调用获取多个目标货币的汇率，可选指定时间点	source、target
list_currencies	所有受支持的代码、名称和符号	—
list_central_banks	所有涵盖的央行 / 税务机关及其代码	—
get_official_rates	指定机构发布的官方汇率表（或其中一个货币对）	bank
get_reference_rate	每个工作日一张固定的中间市场汇率表（伦敦时间 16:00）	—
request_trial_key	无需账户，即可自行获取一个可调用 100 次、有效期 7 天的试用密钥	—

只有 get_historical_rates 和 get_rates_authenticated 需要 ALLRATES_API_KEY：免费密钥可获取最新的多目标汇率；get_historical_rates 和 time 需要付费套餐。输入架构将 additionalProperties 设为 false — 未知字段会被拒绝。各工具的完整参考：mcp-server README。

get_exchange_rate

两种货币之间的当前中间市场汇率。使用密钥时调用 GET /rate；不使用密钥时调用 GET /open/central-bank/{bank}（优先使用 ECB，然后是发行目标货币的银行，最后是源货币对应的银行）。

字段	类型	必需	描述
source	字符串（恰好 3 个字符）	是	ISO 4217 代码，例如 USD
target	字符串（恰好 3 个字符）	是	ISO 4217 代码，例如 EUR

{ "source": "USD", "target": "EUR" }

使用密钥时的响应：

{ "rate": 0.888889, "source": "mid-market" }

不使用密钥时的响应（USD → GBP 不在 ECB 汇率表中，因此由英格兰银行响应；由于该行发布的是反向汇率，所以 derived: true）：

{
  "rate": 0.7598784195,
  "source": "Bank of England official rate (keyless mode)",
  "bank": "boe",
  "rate_date": "2026-10-14",
  "derived": true,
  "note": "Keyless mode: this is the Bank of England official rate published on 2026-10-14, not a live mid-market quote. For real-time rates across 160+ currencies set ALLRATES_API_KEY — free tier at https://allratestoday.com/register."
}

get_historical_rates

指定货币对在固定期间内的时间序列数据点。调用 GET /historical-rates。需要使用付费套餐中的 API 密钥（免费和试用密钥会收到 403 错误）。

字段	类型	必需	描述
source	字符串（恰好 3 个字符）	是	源货币代码
target	字符串（恰好 3 个字符）	是	目标货币代码
period	字符串	否（默认值为 7d）	可选值：1d、7d、30d、1y

各期间的粒度：

period	粒度
1d	每小时
7d	每日
30d	每日
1y	每周

{ "source": "USD", "target": "INR", "period": "30d" }

响应（已截断）：

{
  "source": "USD",
  "target": "INR",
  "period": "30d",
  "data": [
    { "date": "2026-09-17", "rate": 96.1006, "timestamp": 1789603200000 },
    { "date": "2026-09-18", "rate": 95.8142, "timestamp": 1789689600000 },
    "...",
    { "date": "2026-10-16", "rate": 94.9643, "timestamp": 1792108800000 }
  ]
}

get_rates_authenticated

一次调用获取多个目标货币的汇率，可选指定历史时间戳或分组窗口。调用 GET /v1/rates。

字段	类型	必需	描述
source	字符串（恰好 3 个字符）	是	源货币代码
target	字符串	是	一个或多个代码，以逗号分隔（EUR,GBP,JPY）
time	字符串（ISO 8601 日期时间）	否	历史时间点（付费套餐）
group	字符串	否	可选值：hour、day、week、month

{ "source": "USD", "target": "EUR,GBP,JPY" }

响应 — { rates: [{ rate, source, target, time }] }：

{
  "rates": [
    { "rate": 0.888889, "source": "USD", "target": "EUR", "time": "2026-10-16T12:16:01+0000" },
    { "rate": 0.749766, "source": "USD", "target": "GBP", "time": "2026-10-16T12:16:01+0000" },
    { "rate": 157.985, "source": "USD", "target": "JPY", "time": "2026-10-16T12:16:01+0000" }
  ]
}

list_currencies

所有受支持货币的代码、名称和符号。调用 GET /v1/symbols，上游缓存有效期为 24 小时 — 在调用其他工具前，用它验证用户输入的成本很低。

输入 — 无。

响应（已截断）：

{
  "currencies": [
    { "code": "USD", "name": "US Dollar", "symbol": "$" },
    { "code": "EUR", "name": "Euro", "symbol": "€" },
    { "code": "GBP", "name": "British Pound", "symbol": "£" },
    "..."
  ],
  "count": 163
}

list_central_banks

所有官方来源——121 家中央银行，以及 HMRC、美国财政部和瑞士 BAZG——均提供 get_official_rates 作为 bank 接受的 code。无需密钥。调用 GET /open/central-banks（或使用密钥时调用 /v1/central-banks）。

{
  "sources": [
    { "code": "ecb", "name": "European Central Bank", "latest": "2026-10-15", "age_days": 1, "stale": false, "cadence": "daily" },
    { "code": "fed", "name": "US Federal Reserve (H.10)", "latest": "2026-10-09", "age_days": 7, "stale": false, "cadence": "weekly" },
    "..."
  ],
  "stale_count": 3,
  "checked_at": "2026-10-16T12:16:46.232Z"
}

get_official_rates

机构发布的固定且可引用的汇率。输入：bank（必填）、可选的 date（YYYY-MM-DD，付费计划——免费密钥会返回 403 Historical central bank rates require a paid plan），以及可选的 source 和 target，用于查询单个货币对。查询最新汇率表无需密钥。

{
  "bank": "ecb",
  "rate_date": "2026-10-15",
  "source": "EUR",
  "target": "USD",
  "rate": 1.1208,
  "rate_type": "reference",
  "derived": false,
  "method": "published",
  "age_days": 1,
  "stale": false,
  "cadence": "daily",
  "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" }
}

🗺️ 支持的货币

AllRatesToday API 提供的所有货币均可通过这些工具使用——调用 list_currencies 获取权威的实时列表。常用代码包括：

🇺🇸 USD · 🇪🇺 EUR · 🇬🇧 GBP · 🇯🇵 JPY · 🇨🇦 CAD · 🇮🇳 INR

get_exchange_rate 和 get_historical_rates 的 source 和 target 字段会验证是否恰好为三个字符，因此请传入 ISO 4217 代码，而非货币名称。

⚙️ 环境变量

变量	默认值	必填	用途
ALLRATES_API_KEY	—	否	您的 API 密钥，会作为 Bearer 令牌通过 Authorization 标头发送。未设置 ⇒ 无密钥模式；缺少密钥不会导致服务退出。
ALLRATES_BASE_URL	https://allratestoday.com/api	否	用于覆盖为可自托管或预发布部署的地址。末尾的斜杠会被移除。

请在 MCP 客户端的配置（env 区块中）设置这些变量，而不是在 shell 中设置——MCP 服务会作为子进程启动，使用隔离的环境。

🛡️ 错误处理

工具调用失败时会返回一个 isError: true 的 MCP 工具结果。文本格式为 AllRatesToday error (<status>): <message>。

HTTP 状态码	消息
400	API 的 error 字段；若无则为 Bad request — possibly an unknown currency code
401	Invalid AllRatesToday API key
403	HTTP 403 — <upstream message>，例如，免费或试用密钥调用 get_historical_rates 或 time 时会返回 Historical rates require a paid plan…，查询指定日期的汇率表时会返回 Historical central bank rates require a paid plan…
404（无密钥）	No keyless official source covers X/Y. Real-time rates for 160+ currencies need an API key …
429	AllRatesToday API quota exceeded
5xx	HTTP <status> — <upstream message>

在发起任何 HTTP 调用之前，本地引发的错误：

• 无密钥调用 get_rates_authenticated（未指定 time）→ … needs an AllRatesToday API key. The free tier covers it — sign up at https://allratestoday.com/register …
• 无密钥调用 get_historical_rates，或调用带有 time 的 get_rates_authenticated → … needs an AllRatesToday API key on a paid plan …
• 无密钥调用时为 get_official_rates / get_reference_rate 指定 date → … needs an AllRatesToday API key on a paid plan …
• 无法识别的工具名称 → MCP error -32602: Tool <name> not found

由于这些错误以文本形式返回，助手会将其转达给用户——429 错误会显示为 “API 配额已超出。”

🛠️ 故障排查

症状	可能原因	解决方法
客户端显示“MCP 服务启动失败”或红点	不是缺少密钥（0.5.0+ 无密钥也能启动）——通常是 npx 无法访问注册表，或 Node 版本低于 18	在 shell 中运行 npx -y @allratestoday/mcp-server 并查看 stderr
每次调用都返回 401 错误	密钥格式错误、被截断或已撤销	从控制面板复制一个新密钥
调用返回 429 错误	配额已用完——免费套餐不会重置	在 allratestoday.com/pricing 升级
调用返回 403 错误	使用免费或试用密钥调用 get_historical_rates，或在 get_official_rates / get_reference_rate 中使用 time 或 date	历史数据仅限付费用户使用：省略 date/time 以获取最新汇率，或升级
get_historical_rates 返回 400 错误	时间段无效或货币代码未知	period 必须为 1d/7d/30d/1y；代码必须恰好为 3 个字母
服务已启动，但工具始终不显示	客户端在配置变更后未重新加载	完全退出（而非仅关闭）并重新打开客户端
npx 正在运行，但一直挂起	这是正常情况——服务正在等待 MCP 客户端通过 stdio 连接	让 MCP 客户端启动它

若要检查服务正在执行什么操作，请手动运行（有无密钥均可）：

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

没有输出表示运行正常——stdout 专用于 MCP 协议；错误会输出到 stderr。

💡 说明

你们会存储我的对话或查询数据吗？ 不会。只有你的 API 密钥和请求参数（source、target、period、time、group）会发送到 allratestoday.com——绝不会发送模型的对话上下文。

我的 API 密钥会如何处理？ 它只会作为 Bearer 令牌，通过请求 AllRatesToday API 时的 Authorization 标头发送。服务不会记录该密钥。

为什么首次调用很慢？ npx 冷启动（首次运行时会下载软件包），再加上上游缓存未命中。

可以不使用 npm/Node 运行吗？ 目前不可以——engines 要求 Node ≥ 18。如果你需要独立二进制文件，请提交 issue。

有可自托管的选项吗？ 将 ALLRATES_BASE_URL 指向你自己的实例即可。

它能与其他客户端配合使用吗？ 任何使用 stdio 传输的 MCP 兼容宿主都能使用；远程 MCP 客户端可使用托管端点 https://allratestoday.com/api/mcp；此处列出的四个客户端只是提供了配置路径文档的客户端。

👩‍💻 开发

此仓库中的 src/ 是较旧的 0.3.x 快照。已发布的软件包基于 AllRates-Today/mcp-server 构建——请在那里进行开发：

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

npm run build 会运行 tsc；npm run dev 会监视并重新构建；npm start 会运行编译后的服务。CI（.github/workflows/ci.yml）会在每次向 main 推送以及每次拉取请求中，使用 Node 22 运行 npm ci && npm run build。

若要针对本地 AllRatesToday 实例进行测试：

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

项目结构：

src/
├── index.ts      # MCP server, tool definitions, request handlers
├── client.ts     # HTTP client for the AllRatesToday API + error mapping
└── home-banks.ts # currency → issuing central bank (keyless fallback; mcp-server only)
dist/             # Compiled JS (gitignored)
server.json       # MCP registry manifest
smithery.yaml     # Smithery launch config
.mcp.json         # Ready-to-copy client config

欢迎提交 issue 和 PR。提交 PR 前：必须确保 npm run build 成功，使用真实 API 密钥测试变更，并在工具行为发生变化时，同时更新 src/index.ts 中的工具说明和上方的 API 参考文档。

📝 更新日志

完整更新日志：mcp-server README → 更新日志。近期亮点：

• 0.7.6 — 不带密钥的 get_rates_authenticated 搭配 time 会提示需要付费计划；文档说明历史数据仅限付费用户使用
• 0.7.4 — 不带密钥的 get_exchange_rate 会从 ECB 表回退到发行任一货币的中央银行（USD/GBP、GBP/JPY、USD/INR 均可在不带密钥时查询），与托管端点相同；日期表格错误会提示需要付费计划
• 0.7.0 — get_reference_rate（每日参考汇率）和 request_trial_key（自行签发 100 次调用的试用密钥）
• 0.6.0 — 不带密钥的 list_central_banks 和 get_official_rates（121 家中央银行 + 3 个税务机关）
• 0.5.0 — 无密钥模式：服务无需 API 密钥即可启动并响应，而不会退出
• 0.3.x — 所有工具均需要 API 密钥；启动时快速失败并提供清晰说明
• 0.2.x — 移除了新闻工具；get_historical_rates 需要身份验证
• 0.1.x — 初始版本，包含 5 个工具

🔗 链接

• 网站： allratestoday.com
• API 文档： allratestoday.com/docs
• 免费 API 密钥： allratestoday.com/register
• 状态： allratestoday.com/status
• Postman： allratestoday.com/postman
• 支持： allratestoday.com/contact
• npm： @allratestoday/mcp-server
• MCP 协议： modelcontextprotocol.io
• 问题报告： github.com/AllRates-Today/mcp-server/issues
• AI Agent： Claude Code 插件 /plugin marketplace add AllRates-Today/claude-code-plugin · 托管 MCP 端点 https://allratestoday.com/api/mcp（无需密钥）
• 2026 年 10 月新增： Agent 可自行签发试用密钥 — POST https://allratestoday.com/api/agent/keys（JSON）→ 100 次调用 / 7 天 — 并读取无需密钥的每日参考汇率（伦敦时间 16:00 定盘价），地址为 https://allratestoday.com/api/open/reference-rate
• 控制面板： allratestoday.com/profile

📜 许可证

MIT — 参见 LICENSE。