io.github.UniRate-API/mcp

UniRate MCP Server

A Model Context Protocol server for the UniRate API — give Claude, Cursor, Continue, and any MCP-compatible AI assistant first-class access to currency conversion and exchange rates.

• 🔄 Real-time conversion between 170+ currencies (fiat + major crypto)
• 📈 Historical rates back to 1999 (Pro plan)
• 🆓 Free tier, no credit card required — get a key at unirateapi.com
• 🧩 Four tools, fully-typed inputs (Zod schemas), structured outputs
• 🌐 Stdio + Streamable HTTP/SSE transports — run locally or host as a remote MCP endpoint
• ⚡ Pure Node 18+, single dependency on @modelcontextprotocol/sdk

Why this exists

Most "currency for AI" workflows today involve hand-rolled fetch wrappers in custom tools, or generic HTTP MCP servers that hand the model raw JSON. This server gives models a tight, typed, currency-aware tool surface — they ask "what was 100 USD in EUR on 2020-03-15?" and get back a formatted answer plus a structured payload they can chain into other tool calls.

Quick start

1. Install

npm install -g @unirate/mcp

Or run on demand with npx @unirate/mcp (no install).

2. Get a UniRate API key

Free tier covers convert, latest_rate, and list_currencies. Sign up at unirateapi.com — no credit card required.

3. Wire it into your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. The four UniRate tools will appear in the tool picker.

Cursor / Continue / Cline

Add to your MCP config (.cursor/mcp.json, ~/.continue/config.json, etc.):

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

From source

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. Run as a remote endpoint (Streamable HTTP / SSE)

By default the server uses stdio, which is what Claude Desktop and most MCP clients want. To host it as a remote endpoint instead — for shared use, multi-user deployments, or browser-based clients — start it in HTTP mode:

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

That exposes:

• POST /mcp — Streamable HTTP endpoint (SSE-capable). Stateless: a fresh server is built per request, so the same process can serve many concurrent clients.
• GET /healthz — JSON liveness probe ({ "status": "ok", "server": "unirate-mcp", "version": "..." }).

Point any Streamable-HTTP-capable MCP client (Claude Desktop with remote server support, Cursor remote MCP, etc.) at http://your-host:3001/mcp. Drop it behind a reverse proxy + TLS for production.

Docker

Multi-arch images (linux/amd64, linux/arm64) are published to both the GitHub Container Registry (ghcr.io/unirate-api/unirate-mcp) and Docker Hub (unirate/unirate-mcp) — use whichever you prefer:

# 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

Point an MCP client at http://your-host:3001/mcp for the Streamable HTTP transport.

Programmatic / edge runtimes (Cloudflare Workers, Deno, Bun)

The package exports buildServer(client) so you can wire it to whatever transport your runtime prefers. For Workers / Deno / Bun, use the SDK's webStandardStreamableHttp transport with an exported buildServer instance.

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

Tools

convert

Convert an amount from one currency to another at the latest rate.

Example call:

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

Response: human-readable text plus structured { from, to, amount, result }.

latest_rate

Get current exchange rate(s).

historical_rate (Pro plan)

Get the exchange rate that was in effect on a specific date. Coverage back to 1999-01-04 for major fiat pairs.

Free-tier keys receive a clear error pointing to unirateapi.com for upgrade.

list_currencies

Returns the array of supported currency codes (170+) with no parameters. Useful for autocomplete or validating user-supplied codes.

Errors

All UniRate API failures are mapped to friendly tool errors:

Network/timeout errors are wrapped in UnirateError. Tool calls always return a response object with isError: true rather than throwing protocol-level errors, so the model can recover gracefully.

Development

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 ecosystem

UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.

Core clients (9 languages) Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift

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

Static-site generators Astro · Eleventy · Hugo · Jekyll

CMS & e-commerce Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus

Data, AI & backend LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt

Platform & tools MCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian

Money library bridges money gem (Ruby) · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT — see LICENSE.