Realtime Exchange Rate MCP Server

🚀 实时汇率MCP服务器

本项目是一个基于Model Context Protocol（MCP）的服务器，它能让 Claude Code、Cursor、Claude Desktop、Windsurf 以及其他任何支持MCP的客户端获取实时汇率、历史数据和多货币查询信息。通过该服务器，你的AI助手可以回答诸如“当前美元兑欧元的汇率是多少？”“展示过去30天英镑兑日元的走势。”等问题。

🚀 快速开始

本服务器以npm包的形式发布，最简单的安装方式是通过 npx 实现零安装，以下所有配置均采用此方式。

# 无需安装直接运行（推荐）
npx -y @allratestoday/mcp-server

# 或者全局安装
npm install -g @allratestoday/mcp-server
allratestoday-mcp

这两个命令都会启动标准输入输出（stdio）的MCP服务器，并等待客户端连接。这些命令不建议直接在shell中运行，而是由你的MCP客户端作为子进程启动。

✨ 主要特性

📦 安装指南

获取API密钥（必需）

如果没有有效的 ALLRATES_API_KEY，服务器将无法启动。汇率数据由 AllRatesToday 提供，免费密钥足以满足开发和个人使用需求。

1. 在 allratestoday.com/register 注册。
2. 验证你的电子邮件。
3. 从仪表盘复制你的密钥（格式：art_live_xxxxx）。
4. 在以下配置中使用它作为 ALLRATES_API_KEY。

如果缺少密钥，服务器将在标准错误输出中打印清晰的注册说明，并以代码1退出。

安装命令

# 无需安装直接运行（推荐）
npx -y @allratestoday/mcp-server

# 或者全局安装
npm install -g @allratestoday/mcp-server
allratestoday-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，通过询问“当前美元兑欧元的汇率是多少？”来验证设置是否成功。

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

根据不同操作系统编辑相应的配置文件：

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

完全退出并重新打开Claude Desktop（在macOS上使用Cmd+Q，在Windows上右键单击系统托盘图标并选择“退出”）。仅关闭窗口不会重新加载新配置。

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

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

重启Windsurf。

通用标准输入输出MCP客户端

任何支持标准输入输出传输的MCP主机都可以使用。启动命令为：

npx -y @allratestoday/mcp-server

同时需要设置环境变量 ALLRATES_API_KEY。协议版本为MCP 1.x。

验证功能是否正常

配置客户端后，按以下顺序进行测试：

1. 服务器启动：打开客户端。如果MCP集成显示红点或“连接失败”，则API密钥可能缺失或错误（请参阅 故障排除）。
2. 工具列表显示：大多数客户端都有“工具”或“MCP”面板，你应该能看到：
   • get_exchange_rate
   • get_historical_rates
   • get_rates_authenticated
   • list_currencies
3. 实时调用返回结果：向助手询问“当前美元兑欧元的汇率是多少？”助手将调用 get_exchange_rate(source: "USD", target: "EUR") 并返回实际汇率（例如，“当前美元兑欧元的汇率是0.9214。”）。如果助手在未调用工具的情况下编造了一个数字，则说明服务器未连接。

📚 详细文档

工具参考

所有四个工具都需要API密钥。

get_exchange_rate

获取两种货币之间的当前中间市场汇率。 输入参数

调用示例

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

响应示例

{ "rate": 0.92145, "source": "wise" }

get_historical_rates

获取特定时间段内货币对的时间序列数据点。 输入参数

不同时间段的数据粒度

调用示例

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

响应示例（截断）

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

一次调用获取多个目标货币的汇率，可选择指定历史时间戳或分组窗口。 输入参数

调用示例

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

响应示例

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

获取所有支持的货币，包括代码、名称和符号。上游缓存24小时。 输入参数：无。

响应示例（截断）

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

环境变量

这些变量应在MCP客户端的配置中设置（在 env 块中），而不是在shell中设置，因为MCP服务器作为具有隔离环境的子进程启动。

🔧 技术细节

项目结构

src/
├── index.ts      # MCP服务器、工具注册、请求处理程序
└── client.ts     # HTTP客户端 + 错误映射
dist/             # 编译后的JS文件（git忽略）
server.json       # MCP注册表清单
package.json      # npm元数据、依赖项、脚本

开发步骤

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

服务器在标准输入输出上运行，并等待MCP客户端连接。按Ctrl+C退出。

开发过程中的监控和重建

npm run dev

针对本地实例进行测试

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

贡献代码

欢迎在 github.com/cahthuranag/realtime-exchange-rate-mcp 提交问题和拉取请求。在提交拉取请求之前：

1. npm run build 应成功执行且无错误。
2. 使用真实的API密钥（设置在 ALLRATES_API_KEY 中）进行测试。
3. 如果更改了工具行为，请更新 src/index.ts 中的工具描述。
4. 如果添加或重命名了工具，请更新本README的“工具参考”部分。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

常见问题解答

是否会存储我的对话或查询数据？

不会。仅将你的API密钥和请求参数（源货币、目标货币、时间段、时间）发送到上游API，绝不会发送LLM的对话上下文、表格内容或其他任何信息。

API密钥会如何处理？

API密钥仅作为 Bearer 令牌在请求的 Authorization 头中发送到上游API，不会被记录或传输到其他地方。

为什么首次调用历史数据请求很慢？

这是由于 npx 的冷启动（首次运行会下载包）以及上游缓存首次未命中。后续调用通常很快（通常<200ms）。

是否可以在不使用npm/Node的情况下运行？

目前不可以，需要Node ≥18。我们考虑过提供独立二进制文件，如果你对此有需求，请打开一个问题。

是否有自托管选项？

有，将 ALLRATES_BASE_URL 设置为指向你自己的实例。

是否可以与ChatGPT一起使用？

Anthropic MCP标准适用于任何支持MCP的客户端。ChatGPT Desktop有实验性的MCP支持，请查看OpenAI的文档了解当前状态。

故障排除

查看服务器日志

要查看服务器的运行情况，请手动设置API密钥并运行服务器：

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

正常情况下不应有输出（标准输入输出用于MCP协议）。任何错误将输出到标准错误输出。

错误参考

服务器将API错误映射为清晰、可操作的消息。

LLM将在响应中显示这些消息，因此当用户请求触发429错误时，助手将提示“API配额已超出 — 请在下个月重试或升级你的计划。”

变更日志

完整列表请参阅 GitHub Releases。近期亮点：

• 0.3.x — 所有工具都需要API密钥；启动时快速失败并显示清晰的错误信息。
• 0.2.x — 移除新闻工具，get_historical_rates 需要身份验证。
• 0.1.x — 初始版本，包含5个工具。

支持

• Bug报告：github.com/cahthuranag/realtime-exchange-rate-mcp/issues
• MCP问题：modelcontextprotocol.io — 协议文档