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

Certifique-se de que o arquivo de configuração foi salvo corretamente
Reinicie o Claude Desktop completamente
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

Servidor MCP para Claude