Documentação

Servidor MCP para Claude

O que é MCP?

MCP (Model Context Protocol) é um padrão que permite que assistentes de IA como o Claude interajam com ferramentas e fontes de dados externas. Nosso Servidor MCP permite que o Claude consulte países, estados, cidades e códigos postais diretamente nas conversas.

Instalação

Instale globalmente via npm:

npm install -g @countrydataapi/mcp-server

Ou use diretamente com npx (sem instalação necessária):

npx @countrydataapi/mcp-server

Configuração para Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "country-data-api": {
      "command": "npx",
      "args": ["@countrydataapi/mcp-server"],
      "env": {
        "COUNTRY_DATA_API_KEY": "sua-chave-api-aqui"
      }
    }
  }
}

Após salvar a configuração, reinicie o Claude Desktop.

Ferramentas Disponíveis

Uma vez configurado, o Claude terá acesso às seguintes ferramentas:

Países

Ferramenta Descrição
get_countries_all Obter todos os países
get_country_by_name Obter país por nome
get_country_by_code Obter país por código ISO (BR, BRA, 076)
get_countries_by_region Obter países por região (América do Sul, Europa, etc.)
get_countries_by_currency Obter países por moeda (BRL, EUR, etc.)
get_countries_by_language Obter países por idioma (por, eng, etc.)
get_countries_by_timezone Obter países por fuso horário

Estados

Ferramenta Descrição
get_states_all Obter todos os estados/províncias
get_states_by_country Obter estados de um país
get_states_by_city Obter estados que contêm uma cidade

Cidades

Ferramenta Descrição
get_cities_all Obter todas as cidades
get_city Obter cidade por nome
get_cities_by_country Obter cidades de um país
get_cities_by_state Obter cidades de um estado

CEPs

Ferramenta Descrição
get_zipcodes_by_country Obter CEPs de um país
get_zipcodes_by_state Obter CEPs de um estado

Select (Otimizado - 1 token cada)

Ferramenta Descrição
get_select_countries Lista leve de países para dropdowns
get_select_states Lista leve de estados para dropdowns
get_select_cities Lista leve de cidades para dropdowns

Status

Ferramenta Descrição
get_api_status Obter tokens de API restantes

Exemplos de Conversas

Uma vez configurado, você pode perguntar ao Claude coisas como:

Obter Informações de Países

"Quais países estão na América do Sul?" "Me conte sobre o Brasil" "Qual é a capital da Argentina?"

Encontrar Estados/Províncias

"Quais estados existem no Brasil?" "Liste as províncias do Canadá"

Consultas de Cidades

"Quais cidades existem em São Paulo?" "Encontre cidades na região do Rio de Janeiro"

Gerenciamento de Tokens

"Quantos tokens de API eu ainda tenho?"

Parâmetros Comuns

A maioria das ferramentas aceita estes parâmetros opcionais:

Parâmetro Descrição
lang Idioma da resposta: en, es, pt, fr, de, it
fields Lista de campos separados por vírgula para retornar
limitToken Máximo de tokens a usar nesta requisição

Variáveis de Ambiente

Variável Descrição Obrigatório
COUNTRY_DATA_API_KEY Sua chave de API de countrydataapi.com Sim

Solução de Problemas

Claude não vê as ferramentas

  1. Certifique-se de que o arquivo de configuração foi salvo corretamente
  2. Reinicie o Claude Desktop completamente
  3. Verifique se sua chave de API é válida

Erro: Chave de API inválida

Verifique se sua chave de API está correta e tem tokens restantes. Você pode verificar seu saldo de tokens no painel da sua conta.

Ferramentas estão lentas

O servidor MCP usa a mesma API que as requisições diretas. Se as consultas estão lentas, tente:

  • Usar consultas mais específicas (ex.: buscar por país em vez de todos)
  • Limitar resultados com limitToken
  • Usar os endpoints select para dados de dropdown

Notas de Segurança

  • Sua chave de API é armazenada localmente na configuração do Claude Desktop
  • O servidor MCP só se comunica com a Country Data API
  • Nenhum dado é enviado para terceiros

Links