UniRate MCP
Conversão de moedas e taxas de câmbio para assistentes de IA. Mais de 170 moedas, dados históricos desde 1999, plano gratuito, licenciado sob MIT.
Documentação
Servidor UniRate MCP
Um servidor Model Context Protocol para a API UniRate — dando ao Claude, Cursor, Continue e qualquer assistente de IA compatível com MCP acesso de primeira classe à conversão de moedas e taxas de câmbio.
- 🔄 Conversão em tempo real entre mais de 170 moedas (fiat + principais criptomoedas)
- 📈 Taxas históricas desde 1999 (plano Pro)
- 🆓 Plano gratuito, sem necessidade de cartão de crédito — obtenha uma chave em unirateapi.com
- 🧩 Quatro ferramentas, entradas totalmente tipadas (esquemas Zod), saídas estruturadas
- 🌐 Transportes Stdio + Streamable HTTP/SSE — execute localmente ou hospede como um endpoint MCP remoto
- ⚡ Node 18+ puro, dependência única em
@modelcontextprotocol/sdk
Por que isto existe
A maioria dos fluxos de trabalho de "moeda para IA" hoje envolve wrappers de fetch improvisados em ferramentas personalizadas, ou servidores HTTP MCP genéricos que entregam JSON bruto ao modelo. Este servidor dá aos modelos uma superfície de ferramentas enxuta, tipada e consciente de moedas — eles perguntam "quanto era 100 USD em EUR em 2020-03-15?" e recebem uma resposta formatada além de um payload estruturado que podem encadear em outras chamadas de ferramentas.
Início rápido
1. Instalação
npm install -g @unirate/mcp
Ou execute sob demanda com npx @unirate/mcp (sem instalação).
2. Obtenha uma chave de API UniRate
O plano gratuito cobre convert, latest_rate e list_currencies. Cadastre-se em unirateapi.com — sem necessidade de cartão de crédito.
3. Conecte-o ao seu cliente MCP
Claude Desktop
Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"unirate": {
"command": "npx",
"args": ["-y", "@unirate/mcp"],
"env": {
"UNIRATE_API_KEY": "your-api-key-here"
}
}
}
}
Reinicie o Claude Desktop. As quatro ferramentas UniRate aparecerão no seletor de ferramentas.
Cursor / Continue / Cline
Adicione à sua configuração MCP (.cursor/mcp.json, ~/.continue/config.json, etc.):
{
"mcpServers": {
"unirate": {
"command": "npx",
"args": ["-y", "@unirate/mcp"],
"env": { "UNIRATE_API_KEY": "your-api-key-here" }
}
}
}
A partir do código-fonte
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. Execute como um endpoint remoto (Streamable HTTP / SSE)
Por padrão, o servidor usa stdio, que é o que o Claude Desktop e a maioria dos clientes MCP esperam. Para hospedá-lo como um endpoint remoto — para uso compartilhado, implantações multiusuário ou clientes baseados em navegador — inicie-o no modo 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
Isso expõe:
POST /mcp— endpoint Streamable HTTP (com suporte a SSE). Sem estado: um servidor novo é construído por requisição, então o mesmo processo pode atender muitos clientes concorrentes.GET /healthz— sonda de liveness JSON ({ "status": "ok", "server": "unirate-mcp", "version": "..." }).
Aponte qualquer cliente MCP compatível com Streamable HTTP (Claude Desktop com suporte a servidor remoto, Cursor MCP remoto, etc.) para http://your-host:3001/mcp. Coloque-o atrás de um proxy reverso + TLS para produção.
Docker
Imagens multi-arquitetura (linux/amd64, linux/arm64) são publicadas tanto no
GitHub Container Registry
(ghcr.io/unirate-api/unirate-mcp) quanto no Docker Hub
(unirate/unirate-mcp) — use o que preferir:
# 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
Aponte um cliente MCP para http://your-host:3001/mcp para o transporte Streamable HTTP.
Programático / runtimes de borda (Cloudflare Workers, Deno, Bun)
O pacote exporta buildServer(client) para que você possa conectá-lo a qualquer transporte que seu runtime preferir. Para Workers / Deno / Bun, use o transporte webStandardStreamableHttp do SDK com uma instância buildServer exportada.
import { UnirateClient } from "@unirate/mcp/dist/client.js";
import { buildServer } from "@unirate/mcp";
// → connect to your runtime's preferred transport
Ferramentas
convert
Converta um valor de uma moeda para outra na taxa mais recente.
| Parâmetro | Tipo | Obrigatório | Observações |
|---|---|---|---|
from | string | sim | Código ISO 4217 (ex.: USD) |
to | string | sim | Código ISO 4217 (ex.: EUR) |
amount | número | sim | Valor positivo em from |
Exemplo de chamada:
{ "name": "convert", "arguments": { "from": "USD", "to": "EUR", "amount": 100 } }
Resposta: texto legível por humanos além de { from, to, amount, result } estruturado.
latest_rate
Obtenha a(s) taxa(s) de câmbio atual(is).
| Parâmetro | Tipo | Obrigatório | Observações |
|---|---|---|---|
from | string | sim | Moeda base |
to | string | não | Destino. Omita para obter taxas de todas as moedas |
historical_rate (plano Pro)
Obtenha a taxa de câmbio que estava em vigor em uma data específica. Cobertura desde 1999-01-04 para os principais pares de moedas fiat.
| Parâmetro | Tipo | Obrigatório | Observações |
|---|---|---|---|
date | string | sim | YYYY-MM-DD (ex.: 2020-03-15) |
from | string | sim | Moeda de origem |
to | string | sim | Moeda de destino |
amount | número | não | Padrão é 1 |
Chaves do plano gratuito recebem um erro claro apontando para unirateapi.com para upgrade.
list_currencies
Retorna o array de códigos de moedas suportados (170+) sem parâmetros. Útil para autocompletar ou validar códigos fornecidos pelo usuário.
Erros
Todas as falhas da API UniRate são mapeadas para erros de ferramenta amigáveis:
| HTTP | Classe de erro | O que o modelo vê |
|---|---|---|
| 400 | InvalidRequestError | "Parâmetros de requisição inválidos" |
| 401 | AuthenticationError | "Chave de API ausente ou inválida" |
| 403 | ProPlanRequiredError | "…requer Pro… upgrade em https://unirateapi.com" |
| 404 | InvalidCurrencyError | "Moeda não encontrada ou sem dados disponíveis" |
| 429 | RateLimitError | "Limite de taxa excedido" |
| 503 | APIError | "Serviço indisponível" |
Erros de rede/timeout são encapsulados em UnirateError. Chamadas de ferramentas sempre retornam um objeto de resposta com isError: true em vez de lançar erros de nível de protocolo, para que o modelo possa se recuperar com elegância.
Desenvolvimento
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
Ecossistema UniRate
A UniRate oferece integrações oficiais para mais de 40 ecossistemas, todas mantidas sob a organização UniRate-API.
Clientes principais (9 linguagens) Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
JavaScript / TypeScript React · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC
Geradores de site estático Astro · Eleventy · Hugo · Jekyll
CMS e e-commerce Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus
Dados, IA e backend LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt
Plataforma e ferramentas Servidor MCP · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian
Pontes de bibliotecas de dinheiro gem money (Ruby) · NodaMoney (.NET)
Obtenha uma chave de API gratuita em unirateapi.com.
Licença
MIT — veja LICENSE.