APOGEOAPI

@apogeoapi/mcp

Servidor MCP (Model Context Protocol) para ApogeoAPI — dados geográficos, taxas de câmbio em tempo real e geolocalização de IP para Claude Desktop, Cursor e qualquer assistente de IA compatível com MCP.

O que ele faz

Este servidor expõe os endpoints REST da ApogeoAPI como ferramentas que assistentes de IA podem chamar diretamente. Pergunte ao Claude "Qual é a taxa atual do USD para a Argentina?" ou "Geolocalize o IP 8.8.8.8" e ele chamará a ferramenta certa automaticamente.

Ferramentas disponíveis

Ferramenta	Descrição	Plano necessário
get_country	Dados completos do país por código ISO2/ISO3 — nome, capital, região, população, moeda, taxa USD em tempo real, fusos horários, código telefônico	Gratuito
list_countries	Lista paginada de todos os 250+ países	Gratuito
search_countries	Busca de países por nome parcial	Gratuito
get_states	Todos os estados/províncias de um país	Basic+
get_cities	Todas as cidades de um estado por ID numérico do estado	Basic+
get_currency_rate	Taxa de câmbio USD em tempo real para a moeda de um país (atualizada a cada 4 horas)	Basic+
geolocate_ip	País, região, cidade, coordenadas, fuso horário e associação à UE para qualquer IPv4/IPv6	Basic+
global_search	Busca em países, estados e cidades em uma única consulta	Gratuito

Instalação

Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "apogeoapi": {
      "command": "npx",
      "args": ["-y", "@apogeoapi/mcp"],
      "env": {
        "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar o arquivo. As ferramentas da ApogeoAPI aparecerão na lista de ferramentas do Claude.

Cursor

Adicione o mesmo bloco em mcpServers no arquivo de configuração MCP do Cursor (~/.cursor/mcp.json).

Compilação manual

git clone https://github.com/APOGEOAPI/apogeoapi-mcp.git
cd apogeoapi-mcp
npm install
npm run build

Em seguida, referencie o arquivo compilado diretamente:

{
  "mcpServers": {
    "apogeoapi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Obtendo uma chave de API

1. Crie uma conta gratuita em app.apogeoapi.com
2. Vá para API Keys e gere uma nova chave
3. Cole a chave na variável de ambiente APOGEOAPI_KEY acima

Não é necessário cartão de crédito para o plano Gratuito (1.000 req/mês).

Requisitos de plano

Recurso	Gratuito	Basic ($19/mês)	Starter ($29/mês)	Professional ($79/mês)
Países (listar, buscar, obter)	Sim	Sim	Sim	Sim
Busca global	Sim	Sim	Sim	Sim
Estados e cidades	Não	Sim	Sim	Sim
Taxas de câmbio em tempo real	Não	Sim	Sim	Sim
Geolocalização de IP	Não	Sim	Sim	Sim
Requisições mensais	1.000	15.000	100.000	500.000

Faça upgrade em app.apogeoapi.com/dashboard/billing.

Variáveis de ambiente

Variável	Obrigatória	Descrição
APOGEOAPI_KEY	Sim	Sua chave de API do painel
APOGEOAPI_BASE_URL	Não	Substitui a URL base da API (padrão: https://api.apogeoapi.com)

Licença

MIT