UniRate MCP

UniRate MCP 服务

一个适用于 UniRate API 的 Model Context Protocol 服务，让 Claude、Cursor、Continue 及任何兼容 MCP 的 AI 助手都能直接使用货币转换和汇率功能。

• 🔄 实时转换 170 多种货币（法定货币 + 主流加密货币）
• 📈 历史汇率可追溯至 1999 年（Pro 计划）
• 🆓 免费套餐，无需信用卡 — 在 unirateapi.com 获取密钥
• 🧩 四个工具，输入类型完整（Zod schemas），输出结构化
• 🌐 Stdio + Streamable HTTP/SSE 传输方式 — 可在本地运行，也可托管为远程 MCP 端点
• ⚡ 纯 Node 18+，仅依赖 @modelcontextprotocol/sdk

为什么要开发它

如今，大多数“面向 AI 的货币”工作流都依赖自定义工具中的手写 fetch 封装，或是将原始 JSON 交给模型的通用 HTTP MCP 服务。本服务为模型提供了精简、类型明确且支持货币语义的工具接口 — 模型可以询问“2020-03-15 的 100 USD 能兑换多少 EUR？”，并获得格式化答案和结构化数据，以便串联其他工具调用。

快速开始

1. 安装

npm install -g @unirate/mcp

也可以按需运行 npx @unirate/mcp（无需安装）。

2. 获取 UniRate API 密钥

免费套餐支持 convert、latest_rate 和 list_currencies。在 unirateapi.com 注册 — 无需信用卡。

3. 配置 MCP 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "unirate": {
      "command": "npx",
      "args": ["-y", "@unirate/mcp"],
      "env": {
        "UNIRATE_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启 Claude Desktop。四个 UniRate 工具将显示在工具选择器中。

Cursor / Continue / Cline

添加到 MCP 配置（.cursor/mcp.json、~/.continue/config.json 等）：

{
  "mcpServers": {
    "unirate": {
      "command": "npx",
      "args": ["-y", "@unirate/mcp"],
      "env": { "UNIRATE_API_KEY": "your-api-key-here" }
    }
  }
}

从源代码运行

git clone https://github.com/UniRate-API/unirate-mcp.git
cd unirate-mcp
npm install && npm run build
UNIRATE_API_KEY=your-key node dist/index.js

4. 作为远程端点运行（Streamable HTTP / SSE）

默认情况下，服务使用 stdio，这是 Claude Desktop 和大多数 MCP 客户端所需的传输方式。若要将其托管为远程端点，以供共享使用、多用户部署或基于浏览器的客户端使用，请以 HTTP 模式启动：

UNIRATE_API_KEY=your-key unirate-mcp --http 3001
# or via env:
UNIRATE_API_KEY=your-key UNIRATE_MCP_HTTP_PORT=3001 unirate-mcp

这会开放：

• POST /mcp — Streamable HTTP 端点（支持 SSE）。无状态：每个请求都会构建一个全新的服务，因此同一进程可为多个并发客户端提供服务。
• GET /healthz — JSON 存活探针（{ "status": "ok", "server": "unirate-mcp", "version": "..." }）。

将任何支持 Streamable HTTP 的 MCP 客户端（支持远程服务的 Claude Desktop、Cursor 远程 MCP 等）指向 http://your-host:3001/mcp。生产环境中请将其置于反向代理之后并启用 TLS。

Docker

多架构镜像（linux/amd64、linux/arm64）已发布到 GitHub Container Registry （ghcr.io/unirate-api/unirate-mcp）和 Docker Hub （unirate/unirate-mcp）— 可按需选择：

# stdio mode (for local AI clients — pipe stdin/stdout)
docker run --rm -i -e UNIRATE_API_KEY="your-key" \
  ghcr.io/unirate-api/unirate-mcp:latest
# ...or from Docker Hub:
#   docker run --rm -i -e UNIRATE_API_KEY="your-key" unirate/unirate-mcp:latest

# HTTP/SSE mode (hosted endpoint on :3001)
docker run --rm -p 3001:3001 -e UNIRATE_API_KEY="your-key" \
  ghcr.io/unirate-api/unirate-mcp:latest --http 3001

将 MCP 客户端指向 http://your-host:3001/mcp，即可使用 Streamable HTTP 传输方式。

编程接入 / 边缘运行时（Cloudflare Workers、Deno、Bun）

此软件包导出 buildServer(client)，因此你可以将其接入运行时所偏好的任意传输方式。对于 Workers / Deno / Bun，请使用 SDK 的 webStandardStreamableHttp 传输方式，并传入导出的 buildServer 实例。

import { UnirateClient } from "@unirate/mcp/dist/client.js";
import { buildServer } from "@unirate/mcp";
// → connect to your runtime's preferred transport

工具

convert

按最新汇率将一笔金额从一种货币转换为另一种。

Param	Type	Required	Notes
from	string	yes	ISO 4217 代码（例如 USD）
to	string	yes	ISO 4217 代码（例如 EUR）
amount	number	yes	from 中的正数金额

调用示例：

{ "name": "convert", "arguments": { "from": "USD", "to": "EUR", "amount": 100 } }

**响应：**人类可读文本以及结构化的 { from, to, amount, result }。

latest_rate

获取当前汇率。

Param	Type	Required	Notes
from	string	yes	基准货币
to	string	no	目标货币。省略此参数可获取所有货币的汇率

historical_rate (Pro 计划)

获取特定日期生效的汇率。主要法定货币对的覆盖范围可追溯至 1999-01-04。

Param	Type	Required	Notes
date	string	yes	YYYY-MM-DD（例如 2020-03-15）
from	string	yes	源货币
to	string	yes	目标货币
amount	number	no	默认值为 1

免费套餐的密钥会收到明确错误，并提示前往 unirateapi.com 升级。

list_currencies

返回受支持货币代码数组（170 多种），无需参数。可用于自动补全或验证用户提供的代码。

错误

所有 UniRate API 故障都会映射为易于理解的工具错误：

HTTP	Error class	What the model sees
400	InvalidRequestError	“请求参数无效”
401	AuthenticationError	“缺少或无效的 API 密钥”
403	ProPlanRequiredError	“……需要 Pro……请前往 https://unirateapi.com 升级”
404	InvalidCurrencyError	“未找到货币或没有可用数据”
429	RateLimitError	“超出速率限制”
503	APIError	“服务不可用”

网络/超时错误会被包装为 UnirateError。工具调用始终返回带有 isError: true 的响应对象，而不是抛出协议级错误，以便模型能够从容恢复。

开发

npm install
npm run build       # compile TypeScript to dist/
npm test            # 24 mock tests
UNIRATE_LIVE=1 UNIRATE_API_KEY=... npm run test:live  # +4 live free-tier tests

UniRate 生态系统

UniRate 为 40 多种生态系统提供官方集成，均由 UniRate-API 组织维护。

核心客户端（9 种语言） Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift

JavaScript / TypeScript React · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC

静态站点生成器 Astro · Eleventy · Hugo · Jekyll

CMS 与电商 Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus

数据、AI 与后端 LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt

平台与工具 MCP 服务 · 命令行界面 · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian

货币库桥接 money gem (Ruby) · NodaMoney (.NET)

前往 unirateapi.com 获取免费 API 密钥。

许可证

MIT — 参见 LICENSE。