mcp-server-currency-converter by Gustavo-Kuze - MCP Server

Conversor de Moedas MCP

Um servidor MCP (Model Context Protocol) que fornece ferramentas de conversão de moedas e cotações usando a Brasil API, desenvolvido para integração com Claude AI e outros assistentes compatíveis.

🎯 Objetivo

Este projeto permite que assistentes de IA consultem cotações históricas e realizem conversões de moedas em tempo real usando dados da Brasil API. O projeto oferece duas interfaces:

MCP Server: Para integração direta com Claude AI e outros assistentes
API REST Express: Para desenvolvimento e testes rápidos

🚀 Funcionalidades

Tools MCP Disponíveis:

get_exchange_rate_at_date
- Obter cotação de uma moeda em data específica
- Prioriza taxas PTAX quando disponíveis
- Fornece taxas de compra e venda
convert_currency_at_date
- Converter valores entre BRL e moedas estrangeiras
- Suporte para conversão bidirecional (BRL ↔ Moeda estrangeira)
- Usa taxas apropriadas (compra/venda) conforme direção

Moedas Suportadas:

Consulte o endpoint da Brasil API para ver as moedas suportadas:

curl --location 'https://brasilapi.com.br/api/cambio/v1/moedas'

📋 Requisitos

Node.js 18+
pnpm (recomendado) ou npm
TypeScript

🛠️ Instalação

Clone o repositório:

git clone <repository-url>
cd conversor-moeda-mcp

Instale as dependências:

pnpm install
# ou
npm install

Compile o projeto:

pnpm run build
# ou  
npm run build

🏃 Como Rodar Localmente

Opção 1: API Express (Recomendado para Desenvolvimento)

# Iniciar a API Express na porta 3000
pnpm run dev:api

# Ou em produção
pnpm run start:api

A API estará disponível em: http://localhost:3000

Endpoints disponíveis:

GET /health - Health check
POST /api/get-exchange-rate-at-date - Obter cotação
POST /api/convert-currency-at-date - Converter moeda
GET /api-docs - Documentação Swagger interativa
GET /swagger.json - Especificação OpenAPI JSON

Opção 2: MCP Server

# Iniciar o MCP Server
pnpm run dev:mcp

# Ou em produção  
pnpm run start:mcp

🔌 Como Conectar o MCP

No Claude Desktop App

Localize o arquivo de configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione a configuração MCP:

{
  "mcpServers": {
    "conversor-moeda": {
      "command": "node",
      "args": [
        "C:\\caminho\\para\\conversor-moeda-mcp\\build\\index.js"
      ],
      "env": {}
    }
  }
}

Substitua o caminho:
- Altere C:\\caminho\\para\\conversor-moeda-mcp\\build\\index.js pelo caminho real do arquivo compilado
- Use barras duplas \\ no Windows ou barras simples / no macOS/Linux
Reinicie o Claude Desktop

Verificação da Conexão

Após reiniciar o Claude, você deve ver as ferramentas disponíveis:

🔨 get_exchange_rate_at_date
🔨 convert_currency_at_date

📖 Exemplos de Uso

API Express (HTTP)

Obter cotação do USD:

curl -X POST http://localhost:3000/api/get-exchange-rate-at-date \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD","date":"2024-01-15"}'

Converter 100 USD para BRL:

curl -X POST http://localhost:3000/api/convert-currency-at-date \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD", 
    "date": "2024-01-15",
    "direction": "to_brl"
  }'

📚 Documentação Swagger

A API inclui documentação Swagger completa e interativa:

Interface Web: http://localhost:3000/api-docs
JSON Spec: http://localhost:3000/swagger.json

Claude AI (MCP)

Após conectar o MCP, você pode fazer perguntas como:

"Qual era a cotação do dólar em 15 de janeiro de 2024?"
"Converta 500 dólares para reais usando a cotação de ontem"
"Quanto custava 1000 euros em reais no dia 10 de dezembro de 2023?"

🏗️ Estrutura do Projeto

├── src/
│   ├── services/
│   │   └── currency.ts      # Lógica de negócio
│   ├── index.ts             # MCP Server
│   └── server.ts            # API Express
├── docs/
│   ├── DEVELOPMENT.md       # Guia de desenvolvimento
│   └── REFACTORING_SUMMARY.md
├── build/                   # Código compilado
└── package.json

🚀 Scripts Disponíveis

# Desenvolvimento
pnpm run dev:api      # API Express + Swagger em http://localhost:3000/api-docs
pnpm run dev:mcp      # MCP Server + watch mode

# Produção  
pnpm run start:api    # API Express + Swagger
pnpm run start:mcp    # MCP Server

# Utilidades
pnpm run build        # Compilar TypeScript
pnpm run test         # Executar testes

📝 Formato das Datas

Use sempre o formato YYYY-MM-DD
Exemplo: 2024-01-15 para 15 de janeiro de 2024
A Brasil API fornece dados a partir de 2020

🔍 Troubleshooting

MCP não aparece no Claude:

Verifique se o caminho no claude_desktop_config.json está correto
Confirme que pnpm run build foi executado
Reinicie completamente o Claude Desktop
Verifique logs de erro no console do Claude

🚧 Roadmap

Adicionar ferramenta/endpoint para listar moedas suportadas

API não responde:

Confirme que a porta 3000 não está em uso
Verifique se pnpm run dev:api não mostrou erros
Teste o health check: curl http://localhost:3000/health

Cotação não encontrada:

Verifique o formato da data (YYYY-MM-DD)
Confirme que a data não é fim de semana/feriado
Teste com datas recentes (dados mais confiáveis)

🤝 Contribuições

Contribuições são bem-vindas! Por favor:

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo para mais detalhes.

Gustavo-Kuze/mcp-server-currency-converter