{
  "markdown": "# UniRate MCP Server\n\n[![npm](https://img.shields.io/npm/v/@unirate/mcp.svg)](https://www.npmjs.com/package/@unirate/mcp)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the [UniRate API](https://unirateapi.com) — give Claude, Cursor, Continue, and any MCP-compatible AI assistant first-class access to currency conversion and exchange rates.\n\n- 🔄 Real-time conversion between **170+ currencies** (fiat + major crypto)\n- 📈 **Historical rates back to 1999** (Pro plan)\n- 🆓 **Free tier**, no credit card required — get a key at [unirateapi.com](https://unirateapi.com)\n- 🧩 Four tools, fully-typed inputs (Zod schemas), structured outputs\n- 🌐 **Stdio + Streamable HTTP/SSE transports** — run locally or host as a remote MCP endpoint\n- ⚡ Pure Node 18+, single dependency on `@modelcontextprotocol/sdk`\n\n## Why this exists\n\nMost \"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.\n\n## Quick start\n\n### 1. Install\n\n```bash\nnpm install -g @unirate/mcp\n```\n\nOr run on demand with `npx @unirate/mcp` (no install).\n\n### 2. Get a UniRate API key\n\nFree tier covers `convert`, `latest_rate`, and `list_currencies`. Sign up at [unirateapi.com](https://unirateapi.com) — no credit card required.\n\n### 3. Wire it into your MCP client\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"unirate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@unirate/mcp\"],\n      \"env\": {\n        \"UNIRATE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The four UniRate tools will appear in the tool picker.\n\n#### Cursor / Continue / Cline\n\nAdd to your MCP config (`.cursor/mcp.json`, `~/.continue/config.json`, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"unirate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@unirate/mcp\"],\n      \"env\": { \"UNIRATE_API_KEY\": \"your-api-key-here\" }\n    }\n  }\n}\n```\n\n#### From source\n\n```bash\ngit clone https://github.com/UniRate-API/unirate-mcp.git\ncd unirate-mcp\nnpm install && npm run build\nUNIRATE_API_KEY=your-key node dist/index.js\n```\n\n### 4. Run as a remote endpoint (Streamable HTTP / SSE)\n\nBy 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:\n\n```bash\nUNIRATE_API_KEY=your-key unirate-mcp --http 3001\n# or via env:\nUNIRATE_API_KEY=your-key UNIRATE_MCP_HTTP_PORT=3001 unirate-mcp\n```\n\nThat exposes:\n\n- `POST /mcp` — Streamable HTTP endpoint (SSE-capable). Stateless: a fresh server is built per request, so the same process can serve many concurrent clients.\n- `GET /healthz` — JSON liveness probe (`{ \"status\": \"ok\", \"server\": \"unirate-mcp\", \"version\": \"...\" }`).\n\nPoint 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.\n\n#### Docker\n\nMulti-arch images (linux/amd64, linux/arm64) are published to the\n[GitHub Container Registry](https://github.com/UniRate-API/unirate-mcp/pkgs/container/unirate-mcp):\n\n```bash\n# stdio mode (for local AI clients — pipe stdin/stdout)\ndocker run --rm -i -e UNIRATE_API_KEY=\"your-key\" \\\n  ghcr.io/unirate-api/unirate-mcp:latest\n\n# HTTP/SSE mode (hosted endpoint on :3001)\ndocker run --rm -p 3001:3001 -e UNIRATE_API_KEY=\"your-key\" \\\n  ghcr.io/unirate-api/unirate-mcp:latest --http 3001\n```\n\nPoint an MCP client at `http://your-host:3001/mcp` for the Streamable HTTP transport.\n\n#### Programmatic / edge runtimes (Cloudflare Workers, Deno, Bun)\n\nThe 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.\n\n```ts\nimport { UnirateClient } from \"@unirate/mcp/dist/client.js\";\nimport { buildServer } from \"@unirate/mcp\";\n// → connect to your runtime's preferred transport\n```\n\n## Tools\n\n### `convert`\n\nConvert an amount from one currency to another at the latest rate.\n\n| Param   | Type     | Required | Notes                          |\n|---------|----------|----------|--------------------------------|\n| `from`  | string   | yes      | ISO 4217 code (e.g. `USD`)     |\n| `to`    | string   | yes      | ISO 4217 code (e.g. `EUR`)     |\n| `amount`| number   | yes      | Positive amount in `from`      |\n\n**Example call:**\n\n```json\n{ \"name\": \"convert\", \"arguments\": { \"from\": \"USD\", \"to\": \"EUR\", \"amount\": 100 } }\n```\n\n**Response:** human-readable text plus structured `{ from, to, amount, result }`.\n\n### `latest_rate`\n\nGet current exchange rate(s).\n\n| Param  | Type   | Required | Notes                                            |\n|--------|--------|----------|--------------------------------------------------|\n| `from` | string | yes      | Base currency                                    |\n| `to`   | string | no       | Target. **Omit** to get rates for all currencies |\n\n### `historical_rate` *(Pro plan)*\n\nGet the exchange rate that was in effect on a specific date. Coverage back to **1999-01-04** for major fiat pairs.\n\n| Param   | Type   | Required | Notes                              |\n|---------|--------|----------|------------------------------------|\n| `date`  | string | yes      | `YYYY-MM-DD` (e.g. `2020-03-15`)   |\n| `from`  | string | yes      | Source currency                    |\n| `to`    | string | yes      | Target currency                    |\n| `amount`| number | no       | Defaults to 1                      |\n\n> Free-tier keys receive a clear error pointing to [unirateapi.com](https://unirateapi.com) for upgrade.\n\n### `list_currencies`\n\nReturns the array of supported currency codes (170+) with no parameters. Useful for autocomplete or validating user-supplied codes.\n\n## Errors\n\nAll UniRate API failures are mapped to friendly tool errors:\n\n| HTTP | Error class            | What the model sees                                   |\n|------|------------------------|-------------------------------------------------------|\n| 400  | `InvalidRequestError`  | \"Invalid request parameters\"                          |\n| 401  | `AuthenticationError`  | \"Missing or invalid API key\"                          |\n| 403  | `ProPlanRequiredError` | \"…requires Pro… upgrade at https://unirateapi.com\"    |\n| 404  | `InvalidCurrencyError` | \"Currency not found or no data available\"             |\n| 429  | `RateLimitError`       | \"Rate limit exceeded\"                                 |\n| 503  | `APIError`             | \"Service unavailable\"                                 |\n\nNetwork/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.\n\n## Development\n\n```bash\nnpm install\nnpm run build       # compile TypeScript to dist/\nnpm test            # 24 mock tests\nUNIRATE_LIVE=1 UNIRATE_API_KEY=... npm run test:live  # +4 live free-tier tests\n```\n\n<!-- unirate-ecosystem-footer:start -->\n## UniRate ecosystem\n\nUniRate ships official integrations for 40+ ecosystems, all maintained under the\n[UniRate-API](https://github.com/UniRate-API) org.\n\n**Core clients (9 languages)**\n[Python](https://github.com/UniRate-API/unirate-api-python) ·\n[Node.js / TypeScript](https://github.com/UniRate-API/unirate-api-nodejs) ·\n[Go](https://github.com/UniRate-API/unirate-api-go) ·\n[Rust](https://github.com/UniRate-API/unirate-api-rust) ·\n[Java](https://github.com/UniRate-API/unirate-api-java) ·\n[Ruby](https://github.com/UniRate-API/unirate-api-ruby) ·\n[PHP](https://github.com/UniRate-API/unirate-api-php) ·\n[.NET](https://github.com/UniRate-API/unirate-api-dotnet) ·\n[Swift](https://github.com/UniRate-API/unirate-api-swift)\n\n**JavaScript / TypeScript**\n[React](https://github.com/UniRate-API/react-unirate) ·\n[Next.js](https://github.com/UniRate-API/next-unirate) ·\n[Remix](https://github.com/UniRate-API/remix-unirate) ·\n[SvelteKit](https://github.com/UniRate-API/sveltekit-unirate) ·\n[Vue](https://github.com/UniRate-API/vue-unirate) ·\n[Angular](https://github.com/UniRate-API/angular-unirate) ·\n[Nuxt](https://github.com/UniRate-API/nuxt-unirate) ·\n[NestJS](https://github.com/UniRate-API/nestjs-unirate) ·\n[tRPC](https://github.com/UniRate-API/trpc-unirate)\n\n**Static-site generators**\n[Astro](https://github.com/UniRate-API/astro-unirate) ·\n[Eleventy](https://github.com/UniRate-API/eleventy-unirate) ·\n[Hugo](https://github.com/UniRate-API/hugo-unirate) ·\n[Jekyll](https://github.com/UniRate-API/jekyll-unirate)\n\n**CMS & e-commerce**\n[Wagtail](https://github.com/UniRate-API/wagtail-unirate) ·\n[WordPress](https://github.com/UniRate-API/unirate-currency-converter) ·\n[WooCommerce](https://github.com/UniRate-API/unirate-woocs) ·\n[Drupal](https://github.com/UniRate-API/drupal-unirate) ·\n[Strapi](https://github.com/UniRate-API/strapi-plugin-unirate) ·\n[Medusa](https://github.com/UniRate-API/medusa-plugin-unirate) ·\n[Symfony](https://github.com/UniRate-API/unirate-bundle) ·\n[Laravel](https://github.com/UniRate-API/laravel-money-unirate) ·\n[Directus](https://github.com/UniRate-API/directus-extension-unirate)\n\n**Data, AI & backend**\n[LangChain (Python)](https://github.com/UniRate-API/langchain-unirate) ·\n[LangChain.js](https://github.com/UniRate-API/langchain-js-unirate) ·\n[FastAPI](https://github.com/UniRate-API/fastapi-unirate) ·\n[Flask](https://github.com/UniRate-API/flask-unirate) ·\n[Django REST Framework](https://github.com/UniRate-API/djangorestframework-unirate) ·\n[Apache Airflow](https://github.com/UniRate-API/airflow-provider-unirate) ·\n[dbt](https://github.com/UniRate-API/dbt-unirate)\n\n**Platform & tools**\n[MCP server](https://github.com/UniRate-API/unirate-mcp) ·\n[CLI](https://github.com/UniRate-API/unirate-cli) ·\n[Cloudflare Workers](https://github.com/UniRate-API/cloudflare-workers-unirate) ·\n[Home Assistant](https://github.com/UniRate-API/unirate-home-assistant) ·\n[n8n](https://github.com/UniRate-API/n8n-nodes-unirate) ·\n[Google Sheets](https://github.com/UniRate-API/unirate-sheets) ·\n[VS Code](https://github.com/UniRate-API/vscode-unirate) ·\n[Obsidian](https://github.com/UniRate-API/obsidian-currency)\n\n**Money library bridges**\n[money gem (Ruby)](https://github.com/UniRate-API/money-unirate-api) ·\n[NodaMoney (.NET)](https://github.com/UniRate-API/UniRateApi.NodaMoney)\n\nGet a free API key at [unirateapi.com](https://unirateapi.com).\n<!-- unirate-ecosystem-footer:end -->\n\n## License\n\nMIT — see [LICENSE](LICENSE).",
  "bytes": 11019,
  "sha": "6530e04297a00b770eca3ad72ac9d428c19f12f29cda3aa6b4e760805122d194",
  "repo_slug": "unirate-api/unirate-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_unirate_api_mcp_e77af680/readme"
}