IPGeolocation.io MCP Server

Servidor MCP oficial para geolocalização de IP, segurança de IP, contatos de abuso, ASN, fuso horário, astronomia e análise de user-agent.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP IPGeolocation.io

Servidor MCP oficial para IPGeolocation.io. Inclui 16 ferramentas MCP: geolocalização de IP, detecção de ameaças/VPN/proxy, consultas e conversões de fuso horário, dados de nascer/pôr do sol e da lua, detalhes de ASN, contatos de abuso e análise de user-agent. Sete ferramentas funcionam no plano gratuito (1.000 créditos/dia). Planos pagos desbloqueiam todas as 16 além de endpoints em lote (até 50.000 itens por chamada; padrão 1.000, configurável via IPGEOLOCATION_MCP_MAX_BULK_ITEMS).

Funciona com Claude Desktop, Cursor, Windsurf, VS Code, Codex, Cline, Glama e qualquer outro cliente MCP.

Item	Valor
Pacote	`ipgeolocation-io-mcp`
Versão	`2.0.0`
Transporte	`stdio`
Node.js	`>=22`

Início Rápido

Crie uma chave de API IPGeolocation gratuita
Usuários do Cursor podem instalar com um clique:
Adicione isto à configuração do seu cliente MCP (veja Instalar por Cliente abaixo para o caminho exato do arquivo de configuração do seu cliente):

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Reinicie o seu cliente.
Teste: pergunte "Onde está localizado o 8.8.8.8?"

Sumário

Início Rápido
Instalar por Cliente
Verificar se Funciona
Ferramentas por Plano
Referência de Ferramentas
Exemplos de Prompts
Exemplos de Respostas e Saída das Ferramentas
Códigos de Erro
Como Funciona
Cache
Variáveis de Ambiente
Compilando a partir do Código-Fonte
Docker
Testes
Solução de Problemas
Preços
Links
Licença
Política de Privacidade

Instalar por Cliente

Requisitos

Node.js 22 ou posterior
npx disponível no seu terminal
Uma chave de API IPGeolocation.io para a maioria das ferramentas

get_my_ip funciona sem chave de API. Todo o resto exige uma.

Cadastre-se para obter uma chave de API IPGeolocation gratuita

Codex CLI

codex mcp add ipgeolocation --env IPGEOLOCATION_API_KEY=<YOUR_API_KEY> -- npx -y ipgeolocation-io-mcp
codex mcp list

Inicie uma nova sessão do Codex após adicionar o servidor.

Claude Desktop

Adicione a claude_desktop_config.json:

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar. Também enviamos manifest.json para clientes que suportam MCP Bundles.

Cline

Abra o painel MCP Servers > Configure > Advanced MCP Settings. Adicione a cline_mcp_settings.json:

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Reinicie o Cline após salvar.

Cursor

Instalação com um clique:

Ou adicione a .cursor/mcp.json manualmente:

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Reinicie o Cursor após salvar.

Windsurf

Adicione a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Reinicie o Windsurf após salvar.

VS Code / GitHub Copilot

Adicione ao settings.json do seu VS Code:

{
  "mcp": {
    "servers": {
      "ipgeolocation": {
        "command": "npx",
        "args": ["-y", "ipgeolocation-io-mcp"],
        "env": {
          "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

Reinicie o VS Code após salvar.

Glama

Você pode testar o servidor no Glama diretamente. Apenas IPGEOLOCATION_API_KEY é necessário. Deixe os outros campos de variáveis de ambiente vazios, a menos que queira alterar os limites de cache, timeout ou saída.

Se você ainda não tem uma chave, crie uma chave de API IPGeolocation gratuita.

Qualquer Outro Cliente MCP

Use esta configuração:

{
  "command": "npx",
  "args": ["-y", "ipgeolocation-io-mcp"],
  "env": {
    "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
  }
}

Verificar se Funciona

Experimente estes prompts após a configuração:

Prompt	Ferramenta esperada
Onde está localizado o 8.8.8.8?	`lookup_ip`
Para o IP 49.12.212.42, dê-me o veredito de segurança, empresa, ASN e cidade.	`lookup_ip` com `fields` e `include=security`
O 2.56.12.11 é seguro para permitir e qual é o e-mail de contato de abuso?	`lookup_ip` com `include=security,abuse`
Para AS1, liste apenas os números de ASN upstream.	`lookup_asn` com `include=upstreams`
Converta 2026-03-07 09:30 de Nova York para o horário de Tóquio.	`convert_timezone`
Dê os horários do nascer do sol em Karachi de 2026-03-10 a 2026-03-15.	`get_astronomy_time_series`
Analise este user agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36	`parse_user_agent`

Ferramentas por Plano

Plano Gratuito

1.000 créditos por dia. Estas 7 ferramentas estão disponíveis:

Ferramenta	Créditos	O que faz
`lookup_ip`	1	Localização, fuso horário, moeda, ASN para um IP
`get_my_ip`	0	IP público da máquina que executa o servidor
`lookup_currency`	1	Moeda e metadados do país para um IP
`get_timezone`	1	Fuso horário por nome, localização, IP, código de aeroporto ou UN/LOCODE
`convert_timezone`	1	Converte o horário entre dois locais
`get_astronomy`	1	Nascer do sol, pôr do sol, nascer da lua, pôr da lua, crepúsculo, fase da lua para uma data
`get_astronomy_time_series`	1	Dados astronômicos diários para um intervalo de datas (até 90 dias)

Planos Pagos

Todas as 16 ferramentas. Os planos pagos também adicionam network, company e campos estendidos de asn ao lookup_ip, além do parâmetro include para security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code ou *.

Ferramenta	Créditos	O que faz
`bulk_lookup_ip`	1 por IP	Geolocalização em lote, até 50.000 IPs (padrão 1.000)
`check_security`	2	Sinalizadores de VPN, proxy, Tor, bot, spam e ameaças
`bulk_security_check`	2 por IP	Verificações de ameaças em lote
`lookup_company`	1	Nome da empresa e titular do ASN para um IP
`lookup_network`	1	Prefixo de rota, tipo de conexão, status anycast
`parse_user_agent`	1	Analisa uma string de UA em navegador, dispositivo, SO, mecanismo
`bulk_parse_user_agent`	1 por UA	Análise de UA em lote, até 50.000 strings (padrão 1.000)
`lookup_asn`	1	Detalhes de ASN, peers, upstreams, downstreams, rotas, WHOIS
`get_abuse_contact`	1	E-mails de contato de abuso, telefone, endereço, rota

Cálculo de créditos para lookup_ip com include:

Combinação	Total de créditos
Consulta base	1
`include=security`	3
`include=abuse`	2
`include=*`	4
`include=security&fields=security`	2
`include=abuse&fields=abuse`	1

Para detalhes atuais do plano e preços, consulte a página de preços do IPGeolocation.

Referência de Ferramentas

lookup_ip

Consulta de IP único ou domínio. Gratuito e pago. 1 crédito.

Use esta ferramenta quando precisar de localização, fuso horário, moeda ou ASN para um único endereço IP. Em planos pagos, você pode adicionar módulos include para obter dados de segurança, abuso ou hostname na mesma chamada, evitando solicitações extras.

O plano gratuito retorna localização base, metadados do país, moeda, fuso horário e ASN básico. Os planos pagos adicionam network, company, ASN estendido e o parâmetro include. Observe que consultas de domínio exigem um plano pago.

Parâmetro	Obrigatório	Descrição
`ip`	Não	IPv4, IPv6 ou domínio. Consulta de domínio exige plano pago.
`lang`	Não	Idioma da resposta. Idiomas diferentes do inglês exigem plano pago.
`include`	Não	Módulos extras: `security`, `abuse`, `hostname`, `liveHostname`, `hostnameFallbackLive`, `user_agent`, `geo_accuracy`, `dma_code` ou `*`
`fields`	Não	Campos separados por vírgula a retornar
`excludes`	Não	Campos separados por vírgula a excluir
`force_refresh`	Não	Ignora o cache e acessa a API diretamente

Dica: combinar include com fields pode reduzir o custo em créditos. Por exemplo, include=security&fields=security custa 2 créditos em vez de 3 porque você pula a resposta base de geolocalização. Da mesma forma, include=abuse&fields=abuse custa 1 crédito em vez de 2.

bulk_lookup_ip

Consulta de IP em lote. Pago. 1 crédito por IP.

Recebe uma matriz de IPs ou domínios (até 1.000 por padrão, configurável com IPGEOLOCATION_MCP_MAX_BULK_ITEMS). Suporta as mesmas opções de include, fields e excludes que lookup_ip.

Parâmetro	Obrigatório	Descrição
`ips`	Sim	Matriz de endereços IP ou domínios
`lang`	Não	Idioma da resposta
`include`	Não	Módulos extras por IP
`fields`	Não	Campos separados por vírgula a retornar por IP
`excludes`	Não	Campos separados por vírgula a excluir por IP
`force_refresh`	Não	Ignora o cache

get_my_ip

Retorna o IP público da máquina que executa o servidor. Gratuito. 0 créditos. Nenhuma chave de API necessária.

Não recebe parâmetros. Sempre acessa a rede (não usa cache). Útil como uma verificação rápida para confirmar que o processo do servidor está ativo.

check_security

Dados de ameaça e anonimato para um IP. Pago. 2 créditos.

Retorna pontuação de ameaça, sinalizadores de VPN/proxy/Tor, nomes de provedores, pontuações de confiança, indicadores de bot/spam, sinalizadores de anonimato e status de provedor de nuvem.

Se o mesmo prompt também pedir localização, ASN ou dados de abuso, é melhor usar lookup_ip com include=security porque ele agrupa tudo em uma única chamada (3 créditos no total em vez de 2 + 1 separadamente).

Parâmetro	Obrigatório	Descrição
`ip`	Não	Endereço IP a verificar
`fields`	Não	Campos separados por vírgula a retornar
`excludes`	Não	Campos separados por vírgula a excluir
`force_refresh`	Não	Ignora o cache

bulk_security_check

Versão em lote de check_security. Pago. 2 créditos por IP.

Parâmetro	Obrigatório	Descrição
`ips`	Sim	Matriz de endereços IP
`fields`	Não	Campos separados por vírgula a retornar por IP
`excludes`	Não	Campos separados por vírgula a excluir por IP
`force_refresh`	Não	Ignora o cache

get_timezone

Horário atual e detalhes do fuso horário para um local. Gratuito e pago. 1 crédito.

Aceita nomes de fuso horário IANA, coordenadas, endereços IP, códigos de aeroporto (IATA/ICAO) ou UN/LOCODEs. A resposta inclui offsets de fuso horário, variantes de data/datetime, current_time, current_time_unix, time_24, time_12, week, month, year, abreviações de fuso horário e detalhes de transição de horário de verão.

Sempre acessa a rede (não usa cache) porque retorna o horário atual.

Parâmetro	Obrigatório	Descrição
`tz`	Não	Nome do fuso horário IANA (ex.: `America/New_York`)
`lat` + `long`	Não	Latitude e longitude
`location`	Não	String de cidade ou endereço
`ip`	Não	Endereço IP
`iata_code`	Não	Código de aeroporto IATA
`icao_code`	Não	Código de aeroporto ICAO
`lo_code`	Não	UN/LOCODE
`lang`	Não	Idioma da resposta. Idiomas diferentes do inglês exigem plano pago.

convert_timezone

Converte um horário entre dois locais. Gratuito e pago. 1 crédito.

Aceita os mesmos tipos de entrada de localização que get_timezone para origem e destino. Se você omitir o parâmetro time, ele converte o horário atual. Sempre acessa a rede (não usa cache).

Parâmetro	Obrigatório	Descrição
`time`	Não	`yyyy-MM-dd HH:mm` ou `yyyy-MM-dd HH:mm:ss`. O padrão é agora.
`tz_from` / `tz_to`	Não	Nomes de fusos horários IANA
`lat_from` + `long_from`	Não	Coordenadas de origem
`lat_to` + `long_to`	Não	Coordenadas de destino
`location_from` / `location_to`	Não	Strings de cidade/endereço
`iata_from` / `iata_to`	Não	Códigos de aeroporto IATA
`icao_from` / `icao_to`	Não	Códigos de aeroporto ICAO
`locode_from` / `locode_to`	Não	UN/LOCODEs

get_astronomy

Dados de sol e lua para um local em uma data. Gratuito e pago. 1 crédito.

Retorna nascer do sol, pôr do sol, nascer da lua, pôr da lua, crepúsculo matutino e vespertino, meio-dia solar, duração do dia, fase da lua, flags de status do sol/lua e posição ao vivo do sol/lua (altitude, azimute).

Sempre acessa a rede (não é armazenado em cache) porque pular date usa como padrão hoje.

Parâmetro	Obrigatório	Descrição
`lat` + `long`	Não	Coordenadas (maior prioridade quando fornecidas)
`location`	Não	Cidade ou endereço
`ip`	Não	Endereço IP
`date`	Não	`YYYY-MM-DD`. O padrão é hoje.
`elevation`	Não	Metros, 0 a 10000
`time_zone`	Não	Nome IANA para controlar os horários de saída
`lang`	Não	Idioma da resposta. Idiomas diferentes do inglês exigem um plano pago.

get_astronomy_time_series

Dados de astronomia para um intervalo de datas, até 90 dias. Gratuito e pago. 1 crédito por solicitação.

Cada entrada diária inclui mid_night, night_end, morning, sunrise, sunset, evening, night_begin, sun_status, solar_noon, day_length, moon_phase, moonrise, moonset e moon_status. Use isto em vez de chamar get_astronomy repetidamente para um intervalo.

Parâmetro	Obrigatório	Descrição
`dateStart`	Sim	Data de início (`YYYY-MM-DD`)
`dateEnd`	Sim	Data de término (`YYYY-MM-DD`). Intervalo máximo: 90 dias.
`lat` + `long`	Não	Coordenadas (maior prioridade quando fornecidas)
`location`	Não	Cidade ou endereço
`ip`	Não	Endereço IP
`elevation`	Não	Metros
`time_zone`	Não	Nome IANA para controlar os horários de saída
`lang`	Não	Idioma da resposta. Idiomas diferentes do inglês exigem um plano pago.
`force_refresh`	Não	Pular o cache

parse_user_agent

Analisa uma string de UA em dados de navegador, dispositivo, SO e mecanismo. Pago. 1 crédito.

Também classifica bots e rastreadores. Nota: isto analisa o uaString que você fornece. Não infere um UA do chamador a partir da própria conexão MCP.

Parâmetro	Obrigatório	Descrição
`uaString`	Sim	A string de user-agent a ser analisada
`force_refresh`	Não	Pular o cache

Retorna name, type, version, device, engine e operating_system.

bulk_parse_user_agent

Versão em lote de parse_user_agent. Pago. 1 crédito por string.

Aceita até 1.000 strings por solicitação por padrão (configurável com IPGEOLOCATION_MCP_MAX_BULK_ITEMS).

Parâmetro	Obrigatório	Descrição
`uaStrings`	Sim	Matriz de strings de user-agent
`force_refresh`	Não	Pular o cache

lookup_company

Retorna apenas o nome da empresa e o titular do ASN para um IP. Pago. 1 crédito.

Retorna objetos company e asn. lookup_ip retorna os mesmos dados mais localização, fuso horário e muito mais. Use isto quando o par empresa/ASN for tudo o que você precisa e quiser uma resposta menor.

Parâmetro	Obrigatório	Descrição
`ip`	Não	Endereço IP
`force_refresh`	Não	Pular o cache

lookup_currency

Moeda, código de chamada do país, TLD e idiomas para um IP. Gratuito e pago. 1 crédito.

Retorna objetos currency e country_metadata.

Parâmetro	Obrigatório	Descrição
`ip`	Não	Endereço IP
`force_refresh`	Não	Pular o cache

lookup_network

Prefixo de rota, tipo de conexão e status anycast para um IP. Pago. 1 crédito.

Retorna um objeto network com connection_type, route e is_anycast.

Parâmetro	Obrigatório	Descrição
`ip`	Não	Endereço IP
`force_refresh`	Não	Pular o cache

lookup_asn

Consulta completa de ASN. Pago. 1 crédito.

lookup_ip também retorna um objeto asn, mas apenas com metadados básicos. Esta ferramenta retorna o registro completo do ASN, incluindo peers, upstreams, downstreams, rotas e WHOIS. Chame-a uma vez com os campos include que você precisa e depois filtre localmente em vez de fazer várias chamadas para diferentes partes.

Parâmetro	Obrigatório	Descrição
`asn`	Não	ASN (por exemplo, `AS13335` ou `13335`)
`ip`	Não	Endereço IP para resolver para um ASN
`include`	Não	`peers`, `downstreams`, `upstreams`, `routes`, `whois_response`
`fields`	Não	Campos separados por vírgula para retornar
`excludes`	Não	Campos separados por vírgula para excluir
`force_refresh`	Não	Pular o cache

get_abuse_contact

Detalhes do contato de abuso para um IP. Pago. 1 crédito.

Retorna a rota de abuso, país, nome do contato, organização, endereço, endereços de e-mail e números de telefone. Se você também precisar de dados de geolocalização ou segurança para o mesmo IP, use lookup_ip com include=abuse (ou include=security,abuse) para obter tudo em uma única chamada.

Parâmetro	Obrigatório	Descrição
`ip`	Não	Endereço IP
`fields`	Não	Campos separados por vírgula para retornar
`excludes`	Não	Campos separados por vírgula para excluir
`force_refresh`	Não	Pular o cache

Exemplos de Prompts

Verificar se um IP é seguro

O 49.12.212.42 é seguro para confiar em nossa rede? Dê-me o resumo de ameaças e a cidade.
Verifique estes IPs para indicadores de VPN, proxy, Tor, bot e spam: 49.12.212.42, 2.56.12.11, 8.8.8.8
Para 203.0.113.42, diga-me a pontuação de ameaça, se é um provedor de nuvem e se parece um relay.

Descobrir quem possui um IP

Quem usa 1.1.1.1 e qual ASN o roteia?
Para AS24940, liste apenas os números de ASN upstream.
Este IP é anycast e qual prefixo de rota é anunciado para ele: 1.1.1.1

Obter contatos de abuso

Para o IP 2.56.12.11, dê-me o e-mail do contato de abuso, número de telefone e organização.
Preciso do contato de abuso para 1.0.0.0 e da rota de rede envolvida.
Para este IP, mostre-me apenas os detalhes do contato de abuso: 198.51.100.27

Consultas e conversões de fuso horário

Que horas são em Tóquio agora?
Converta 2026-03-07 09:30 de Nova York para o horário de Tóquio.
Qual é a hora local atual no aeroporto JFK?

Dados de nascer do sol, pôr do sol e lua

Dê-me o nascer e o pôr do sol para Londres em 2026-06-21.
Mostre os horários do nascer do sol em Karachi de 2026-03-10 a 2026-03-15.
Para Nova York, dê-me a fase da lua e a duração do dia em 2026-07-17.

Analisar strings de user-agent

Analise este user agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9
Analise estes user agents em lote e diga-me o navegador, SO e tipo de dispositivo para cada um.
Este user agent parece um rastreador ou bot? Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)

Exemplos de Respostas e Saída de Ferramentas

As respostas em texto abaixo mostram o que um cliente pode dizer. A redação exata depende do modelo. Os blocos JSON mostram a saída bruta da ferramenta, reduzida para legibilidade.

Consulta de IP único

Prompt: Localize 91.128.103.196 e dê-me o país, cidade, ASN e hora local.

Exemplo de resposta: 91.128.103.196 está em Estocolmo, Suécia. O ASN é AS1257, operado pela Tele2 Sverige AB. O fuso horário é Europe/Stockholm, a hora local era 2026-02-12 18:36:54.

{
  "ip": "91.128.103.196",
  "location": {
    "country_name": "Sweden",
    "state_prov": "Stockholms lan",
    "city": "Stockholm"
  },
  "asn": {
    "as_number": "AS1257",
    "organization": "Tele2 Sverige AB",
    "country": "SE"
  },
  "time_zone": {
    "name": "Europe/Stockholm",
    "current_time": "2026-02-12 18:36:54.401+0100"
  }
}

Conversão de horário

Prompt: Converta 2025-01-21 13:42:52 de DXB para LHR.

Exemplo de resposta: 2025-01-21 13:42:52 em Dubai converte para 2025-01-21 09:42:52 em Londres. A diferença é de 4 horas.

{
  "original_time": "2025-01-21 13:42:52",
  "converted_time": "2025-01-21 09:42:52",
  "diff_hour": 4,
  "diff_min": 240
}

Contato de abuso

Prompt: Dê-me o contato de abuso para 1.0.0.0.

Exemplo de resposta: O contato de abuso para 1.0.0.0 é IRT-APNICRANDNET-AU na Austrália, cobrindo a rota 1.0.0.0/24. E-mail: helpdesk@apnic.net.

{
  "ip": "1.0.0.0",
  "abuse": {
    "route": "1.0.0.0/24",
    "country": "AU",
    "name": "IRT-APNICRANDNET-AU",
    "address": "PO Box 3646, South Brisbane, QLD 4101, Australia",
    "emails": ["helpdesk@apnic.net"]
  }
}

Códigos de Erro

Todas as ferramentas retornam erros estruturados em vez de travar o servidor. Erros de API incluem o status/mensagem upstream mais um campo guidance para que clientes MCP possam dizer ao usuário o que verificar em seguida, em vez de apenas repetir a resposta upstream.

Código	Significado
`400`	Parâmetros inválidos, formato de data/hora inválido, par de coordenadas ausente ou entrada não suportada
`401`	Chave de API ausente/inválida, plano gratuito chamando uma ferramenta paga ou `lang` não inglês no plano gratuito
`404`	Recurso não encontrado (por exemplo, ASN não existe)
`405`	Restrição de método ou assinatura da API upstream
`413`	Corpo do POST maior do que a API upstream permite
`415`	Solicitação POST sem o tipo de conteúdo `application/json` obrigatório
`423`	IP bogon ou privado (`10.x.x.x`, `192.168.x.x`, etc.)
`429`	Limite diário de solicitações (plano gratuito) ou cota de assinatura/sobretaxa excedida
`499`	Tempo limite de solicitação ou conexão do lado do cliente muito curto
`5xx`	Erro do lado do servidor da API upstream
`502`	O servidor não conseguiu alcançar a API upstream
`504`	A API upstream expirou

Os códigos de status exatos podem variar por endpoint e modo de solicitação. Se um endpoint upstream retornar um status fora desta tabela, o servidor não adivinha a causa. Ele repassa o status e a mensagem upstream com category: "undocumented_api_error" e adiciona orientação para o cliente MCP explicar a resposta como um status upstream não documentado, sem inventar uma causa.

Como Funciona

Este é um servidor MCP stdio que encapsula as APIs v3 do ipgeolocation.io.

Em tempo de execução:

Seu cliente MCP inicia o processo do servidor.
O cliente lê a lista de ferramentas.
Quando um prompt corresponde a uma ferramenta, o cliente a chama.
O servidor valida entradas, chama nossa API e retorna JSON estruturado.
Respostas armazenáveis em cache são mantidas na memória do processo, para que solicitações idênticas repetidas pulem a chamada de API.

Solicitações upstream autenticadas enviam a chave de API no cabeçalho x-ipgeolocation-api-key. A chave não é adicionada às URLs de solicitação.

lookup_company, lookup_currency e lookup_network são wrappers em torno de partes da resposta completa de consulta de IP. Eles existem como ferramentas separadas para que clientes MCP possam descobri-los quando um usuário precisar apenas de um dado.

Cache

Ferramentas que retornam dados estáveis (não consultas de hora atual) armazenam suas respostas em cache na memória do processo. Consultas repetidas são mais rápidas e não usam créditos adicionais. Novas tentativas do cliente não geram chamadas de API duplicadas.

Cache em nível de processo, não memória do cliente ou do modelo
Entradas de cache são limitadas por chave de API, então sessões MCP separadas não compartilham dados upstream em cache
TTL padrão: 5 minutos (300000 ms)
O cache é redefinido quando o processo do servidor é interrompido
Falhas de cache na expiração do TTL, parâmetros alterados ou force_refresh: true Em cache: lookup_ip, bulk_lookup_ip, check_security, bulk_security_check, lookup_company, lookup_currency, lookup_network, parse_user_agent, bulk_parse_user_agent, lookup_asn, get_abuse_contact, get_astronomy_time_series

Sempre ao vivo (não em cache): get_my_ip, get_timezone, convert_timezone, get_astronomy

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`IPGEOLOCATION_API_KEY`	Sim (na maioria das ferramentas)		Sua chave de API do ipgeolocation.io
`IPGEOLOCATION_REQUEST_TIMEOUT_MS`	Não	`15000`	Tempo limite de upstream em ms. Intervalo: 1000-120000
`IPGEOLOCATION_MCP_CACHE_TTL_MS`	Não	`300000`	TTL do cache em ms. Intervalo: 1000-3600000
`IPGEOLOCATION_MCP_CACHE_MAX_ENTRIES`	Não	`500`	Máximo de entradas antes da remoção. Intervalo: 10-5000
`IPGEOLOCATION_MCP_MAX_BULK_ITEMS`	Não	`1000`	Máximo de itens por solicitação em lote. Máximo: 50000
`IPGEOLOCATION_MCP_MAX_RESULT_ITEMS`	Não	`250`	Máximo de itens de array antes da truncagem
`IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS`	Não	`200000`	Comprimento máximo do texto de resposta
`IPGEOLOCATION_MCP_MAX_ERROR_CHARS`	Não	`4000`	Comprimento máximo do texto de erro

Compilando a partir do Código-Fonte

git clone https://github.com/IPGeolocation/ipgeolocation-io-mcp.git
cd ipgeolocation-io-mcp
npm install
npm run build

Execute diretamente:

IPGEOLOCATION_API_KEY=<YOUR_KEY> node dist/cli.js

Inspecione com o MCP Inspector:

IPGEOLOCATION_API_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

Docker

docker build -t ipgeolocation-mcp .
docker run -e IPGEOLOCATION_API_KEY=<YOUR_KEY> ipgeolocation-mcp

Testes

npm test               # full suite
npm run test:unit      # unit tests only
npm run test:integration  # integration tests only

Solução de Problemas

O cliente usa uma ferramenta antiga após a atualização: Reinicie o cliente e confirme que ele carregou a versão mais recente do npm.

Erros 401: Verifique se IPGEOLOCATION_API_KEY está definido na sua configuração. Algumas ferramentas são exclusivas para planos pagos e retornam 401 no plano gratuito. Consultas de domínio em lookup_ip também exigem um plano pago.

Erros 423: Você passou um IP privado/bogon como 10.0.0.1 ou 192.168.1.1. Eles não possuem dados de geolocalização.

Tempos limite 504: A API upstream não respondeu a tempo. Aumente o tempo limite com IPGEOLOCATION_REQUEST_TIMEOUT_MS (padrão: 15000 ms, máximo: 120000 ms).

Preços

Para detalhes atuais do plano, créditos e preços, consulte a página de preços do IPGeolocation.

Licença

MIT

Política de Privacidade

Leia a Política de Privacidade do IPGeolocation.