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 — 協議文檔