CurrencyFreaks

CurrencyFreaks MCP 服务

CurrencyFreaks 的官方 MCP 服务。提供 7 个 MCP 工具，用于查询 1,000 多种法定货币、加密货币和贵金属的实时及历史汇率，并进行货币换算。你只需用通俗的英语向 AI 助手询问汇率，MCP 服务便会处理 API 调用。

适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Cline、Codex 及任何其他兼容 MCP 的客户端。

项目	值
软件包	@currencyfreaks/mcp
传输方式	stdio
Node.js	>=18

快速开始

1. 获取免费的 CurrencyFreaks API 密钥——每月 1,000 次请求，无需信用卡。

2. Cursor 用户可以一键安装：

   

3. 其他用户：将以下内容添加到 MCP 客户端配置中（准确的文件路径请参阅按客户端安装）：

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

4. 重启客户端。

5. 测试：询问 “当前 EUR 兑 USD 的汇率是多少？”

目录

• 快速开始
• 按客户端安装
• 验证是否正常运行
• 工具参考
• 套餐要求
• 提示词示例
• 示例回答和工具输出
• 错误代码
• 工作原理
• 环境变量
• 从源代码构建
• 故障排除
• 定价
• 链接
• 许可证

按客户端安装

要求

• Node.js 18 或更高版本
• 终端中可用的 npx
• CurrencyFreaks API 密钥——免费注册

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code

claude mcp add currencyfreaks --env CURRENCYFREAKS_API_KEY=<YOUR_API_KEY> -- npx -y @currencyfreaks/mcp

添加服务后，启动新的 Claude Code 会话。

Cursor

一键安装：

或者手动添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cursor。

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Windsurf。

VS Code / GitHub Copilot

将以下内容添加到 VS Code 的 settings.json：

{
  "mcp": {
    "servers": {
      "currencyfreaks": {
        "command": "npx",
        "args": ["-y", "@currencyfreaks/mcp"],
        "env": {
          "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

保存后重启 VS Code。

Cline

打开 MCP Servers 面板 → Configure → Advanced MCP Settings。将以下内容添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cline。

Codex CLI

codex mcp add currencyfreaks --env CURRENCYFREAKS_API_KEY=<YOUR_API_KEY> -- npx -y @currencyfreaks/mcp
codex mcp list

添加服务后，启动新的 Codex 会话。

任何其他 MCP 客户端

使用以下配置：

{
  "command": "npx",
  "args": ["-y", "@currencyfreaks/mcp"],
  "env": {
    "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
  }
}

验证是否正常运行

完成设置后，尝试以下问题：

提示词	预期工具
当前欧元兑美元汇率是多少？	get_latest_rates，并设置 symbols=EUR
将 500 USD 兑换成 PKR。	convert_currency
2026-01-15 时，1,000 GBP 值多少 JPY？	convert_currency，并设置 date
2020 年 1 月 2 日的 EUR/USD 汇率是多少？	get_historical_rates
显示 2026 年 8 月第一周的 USD 兑 INR 每日汇率。	get_time_series
自 6 月 1 日以来，日元兑美元汇率变动了多少？	get_fluctuation
尼泊尔卢比的货币代码是什么？	list_currencies，并设置 search=nepal
50 USD 可兑换成 IP 182.186.18.9 所在地的多少当地货币？	ip_to_currency

工具参考

全部 7 个工具均封装 CurrencyFreaks v2.0 REST API。接受 symbols 的工具支持以逗号分隔的货币代码列表（例如 EUR,GBP,PKR），且不区分大小写。使用 list_currencies 查询代码；法定货币、加密货币和贵金属合计超过 1000 种。

贵金属使用 ISO 4217 代码：XAU（黄金）、XAG（白银）、XPT（铂金）、XPD（钯金）。API 将所有汇率和金额以字符串形式返回，以保持精度。

list_currencies

GET /v2.0/currency-symbols（精简版）或 GET /v2.0/supported-currencies（详细版）——受支持的货币目录。无需 API 密钥。

参数	必填	描述
search	否	按代码、名称或（设置 detailed 时）国家名称进行不区分大小写的子串匹配，例如 rupee、PK、bitcoin
detailed	否	true 会返回每种货币的国家、状态（AVAILABLE/DEPRECATED）、历史数据范围 availableFrom/availableUntil 和旗帜图标。默认值为 false。可与 search 一起使用；完整的详细目录约为 270 KB。

get_latest_rates

GET /v2.0/rates/latest——一个或多个货币相对于基准货币的最新汇率。刷新频率取决于套餐：Developer（免费）为每日一次，Starter 为每小时一次，Growth 为每 10 分钟一次，Professional 及以上为每 60 秒一次。

参数	必填	描述
symbols	否	以逗号分隔的货币代码。省略则返回全部 1000 多种货币。
base	否	基准货币代码。默认值为 USD。仅限付费套餐。

convert_currency

GET /v2.0/convert/latest；提供 date 时使用 GET /v2.0/convert/historical——在两种货币之间兑换金额。仅限付费套餐。

参数	必填	描述
from	是	源货币代码
to	是	目标货币代码
amount	否	要兑换的金额，必须大于 0。默认值为 1.0。
date	否	YYYY-MM-DD。按该日汇率兑换，而非使用最新汇率。

get_historical_rates

GET /v2.0/rates/historical——指定历史日期的汇率。主要法定货币的数据可追溯至 1984-11-28；较新的货币和加密货币则从各自的上市日期开始提供数据。仅限付费套餐。

参数	必填	描述
date	是	YYYY-MM-DD
symbols	否	以逗号分隔的货币代码。省略则返回全部货币。
base	否	基准货币代码。默认值为 USD。

get_time_series

GET /v2.0/timeseries——两个日期之间的每日汇率，每天一条记录。仅限 Professional 及以上套餐。

参数	必填	描述
startDate	是	YYYY-MM-DD
endDate	是	YYYY-MM-DD
symbols	否	以逗号分隔的货币代码
base	否	基准货币代码。默认值为 USD。

get_fluctuation

GET /v2.0/fluctuation — 查询两日期间各货币的变动情况：起始汇率、结束汇率、绝对变动值和百分比变动。需使用 Professional 套餐或更高套餐。

符号约定：change 的计算方式为 startRate - endRate。change 为正数表示汇率下跌（计价货币相对于基准货币升值）；为负数表示汇率上涨（计价货币相对于基准货币贬值）。

参数	必填	描述
startDate	是	YYYY-MM-DD
endDate	否	YYYY-MM-DD。默认为今天的前一天。
symbols	否	以逗号分隔的货币代码
base	否	基准货币代码。默认为 USD。

ip_to_currency

GET /v2.0/iptocurrency — 根据 IP 地址的地理位置解析当地货币，并将金额兑换为该货币。目标货币会返回在 to 字段中。需使用 Growth 套餐或更高套餐。

参数	必填	描述
from	是	要兑换的来源货币代码
ip	否	IPv4 或 IPv6 地址。省略时使用调用方自己的 IP。
amount	否	要兑换的金额。默认为 1.0。

套餐要求

功能	最低套餐
list_currencies	无（无需 API 密钥）
使用默认 USD 基准货币的 get_latest_rates	Developer（免费）
任意工具中的 base 参数	Starter
convert_currency	Starter
get_historical_rates	Starter
ip_to_currency	Growth
get_time_series	Professional
get_fluctuation	Professional

超出套餐限制的调用会返回 402 错误，并提供相关指引（参见错误代码）。

提示词示例

实时汇率

• 当前 EUR 兑 USD 的汇率是多少？
• 给我最新的 GBP、JPY 和 CHF 兑欧元汇率。
• 比特币现在值多少美元？
• 黄金价格折合欧元是多少？

兑换

• 将 250 USD 兑换成印度卢比。
• 1,200 欧元可以兑换多少日元？
• 2025-12-31 时，500 GBP 值多少 USD？

历史数据

• 2020 年 1 月 2 日的 USD 兑 PKR 汇率是多少？
• 显示 2026 年第一季度每日 EUR/USD 汇率。
• 对比过去 30 天英镑和欧元兑美元的走势。

价格变动

• 自 1 月 1 日以来，土耳其里拉兑美元贬值了多少？
• 本月 ETH 兑 USD 是涨了还是跌了？变动幅度是多少？

查询

• 哈萨克斯坦坚戈的货币代码是什么？
• CurrencyFreaks 支持哪些非洲货币？
• 尼日利亚奈拉的历史数据可以追溯到多久以前？

示例回答和工具输出

文本回答展示了客户端可能给出的内容；具体措辞取决于模型。JSON 代码块是原始工具输出。

最新汇率

提示词： 最新的 EUR、GBP 和 PKR 兑美元汇率是多少？

示例回答： 截至 2026-08-25 13:26 UTC，1 USD 可兑换 0.9279 EUR、0.8173 GBP 或 281.62 PKR。

{
  "date": "2026-08-25 13:26:00+00",
  "base": "USD",
  "rates": {
    "EUR": "0.9278605451274349",
    "GBP": "0.8172754173817152",
    "PKR": "281.6212943333344",
    "USD": "1.0"
  }
}

兑换

提示词： 将 500 USD 兑换成 PKR。

示例回答： 按照 281.683 的汇率，500 USD 可兑换 140,841.48 PKR。

{
  "date": "2026-08-25 15:22:00+00",
  "from": "USD",
  "to": "PKR",
  "rate": "281.683",
  "givenAmount": "500.0",
  "convertedAmount": "140841.475"
}

汇率变动

提示词： 2026 年 6 月 1 日至 6 月 15 日期间，巴基斯坦卢比兑英镑的走势如何？

示例回答： PKR 兑英镑升值，汇率从每 GBP 兑换 254.331 PKR 变为 243.874 PKR，变动了 10.457（4.11%）。

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-15",
  "base": "GBP",
  "rateFluctuations": {
    "PKR": {
      "startRate": "254.331",
      "endRate": "243.874",
      "change": "10.457",
      "percentChange": "4.11"
    }
  }
}

货币查询

提示词： 尼泊尔卢比的货币代码是什么？

示例回答： 尼泊尔卢比的代码是 NPR。

{
  "count": 6,
  "currencies": {
    "SCR": "Seychellois Rupee",
    "MUR": "Mauritius Rupee",
    "INR": "Indian Rupee",
    "PKR": "Pakistani Rupee",
    "LKR": "Sri Lankan Rupee",
    "NPR": "Nepalese Rupee"
  }
}

错误代码

工具调用不会导致服务崩溃。上游错误会以结构化工具结果的形式返回，其中包含 error、code、message 和 guidance 字段，让客户端能够说明出错原因，而不是只复述状态代码。

代码	含义
400	缺少 API 密钥，或参数无效（货币代码、日期格式、金额或 IP 地址错误）
401	API 密钥无效或未激活 — 检查客户端配置中的 CURRENCYFREAKS_API_KEY
402	当前套餐不包含此功能 — 请参阅套餐要求
404	未找到请求货币、日期或时间间隔对应的汇率
429	每月请求配额已用尽 — 请升级套餐或等待配额重置
499	请求上游 API 超时（参见 CURRENCYFREAKS_REQUEST_TIMEOUT_MS）
502	服务无法连接到上游 API

无效密钥的错误结果示例：

{
  "error": "Invalid Api Access Exception",
  "code": 401,
  "message": "Provided API key is invalid. [Contact tech. support for assistance at [email protected]]",
  "guidance": "The API key is invalid or inactive. Check CURRENCYFREAKS_API_KEY in your MCP client config and confirm the key is active on the CurrencyFreaks dashboard."
}

工作原理

这是一个通过 stdio 封装 CurrencyFreaks v2.0 REST API 的 MCP 服务。

运行时：

1. MCP 客户端通过 npx 启动服务进程。
2. 客户端读取工具列表。
3. 当提示词匹配某个工具时，客户端便会调用它。
4. 服务验证输入、调用 CurrencyFreaks，并返回结构化 JSON。

每次调用时，都会从环境变量读取 API 密钥，并将其作为 apikey 查询参数发送。list_currencies 背后的目录端点是公开的，因此即使尚未配置密钥，该工具也能使用。

环境变量

变量	必需	默认值	描述
CURRENCYFREAKS_API_KEY	是		你的 CurrencyFreaks API 密钥
CURRENCYFREAKS_REQUEST_TIMEOUT_MS	否	15000	上游请求超时时间，单位为 ms

从源代码构建

git clone https://github.com/CurrencyFreaks/currencyfreaks-mcp.git
cd currencyfreaks-mcp
npm install
npm run build

直接运行：

CURRENCYFREAKS_API_KEY=<YOUR_KEY> node dist/cli.js

使用 MCP Inspector 检查：

CURRENCYFREAKS_API_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

故障排除

更新后客户端仍使用旧的工具列表： 重启客户端，并确认它加载了最新的 npm 版本。

400 "Please provide API Key"： 客户端配置的 env 块中未设置 CURRENCYFREAKS_API_KEY。

401 错误： 密钥错误或未激活。请从 CurrencyFreaks 控制面板重新复制密钥。

402 错误： 此工具需要更高级别的套餐。请参阅套餐要求。Developer（免费）套餐仅支持使用默认 USD 基础货币的 get_latest_rates 和 list_currencies。

404 "Rates of provided currency X are available from A to B"： 日期超出了该货币的数据范围。调用 list_currencies 时设置 search=X 和 detailed=true，查看 availableFrom 和 availableUntil。

响应过大： 对汇率工具始终传入 symbols，对 list_currencies 始终传入 search。如果不传这些参数，API 会返回全部 1000 多种货币。

499 超时： 上游 API 未能及时响应。请增大 CURRENCYFREAKS_REQUEST_TIMEOUT_MS（默认值：15000 ms）。

定价

Developer 套餐免费，每月 1,000 次请求，无需信用卡。付费套餐支持选择基础货币、货币转换、历史数据、时间序列、汇率波动和 IP 转货币，并提供更快的刷新速率。请参阅 CurrencyFreaks 定价页面。

链接

• CurrencyFreaks 网站
• API 文档
• 支持的货币
• 定价
• 免费注册
• GitHub 仓库

许可证

MIT