IPGeolocation.io MCP Server

Servidor MCP oficial para geolocalización de IP, seguridad de IP, contactos de abuso, ASN, zona horaria, astronomía y análisis de agente de usuario.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de IPGeolocation.io

Servidor MCP oficial para IPGeolocation.io. Incluye 16 herramientas MCP: geolocalización de IP, detección de amenazas/VPN/proxy, consultas y conversiones de zona horaria, datos de amanecer/atardecer/luna, detalles de ASN, contactos de abuso y análisis de user-agent. Siete herramientas funcionan en el plan gratuito (1,000 créditos/día). Los planes de pago desbloquean las 16 herramientas más los endpoints masivos (hasta 50,000 elementos por llamada; por defecto 1,000, configurable mediante IPGEOLOCATION_MCP_MAX_BULK_ITEMS).

Funciona con Claude Desktop, Cursor, Windsurf, VS Code, Codex, Cline, Glama y cualquier otro cliente MCP.

Elemento	Valor
Paquete	`ipgeolocation-io-mcp`
Versión	`2.0.0`
Transporte	`stdio`
Node.js	`>=22`

Inicio Rápido

Crea una clave API gratuita de IPGeolocation
Los usuarios de Cursor pueden instalarlo con un clic:
Añade esto a la configuración de tu cliente MCP (consulta Instalación por Cliente a continuación para la ruta exacta del archivo de configuración de tu cliente):

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

Reinicia tu cliente.
Pruébalo: pregunta "¿Dónde está 8.8.8.8?"

Tabla de Contenidos

Inicio Rápido
Instalación por Cliente
Verificar que Funciona
Herramientas por Plan
Referencia de Herramientas
Ejemplos de Prompts
Ejemplos de Respuestas y Salida de Herramientas
Códigos de Error
Cómo Funciona
Caché
Variables de Entorno
Compilar desde el Código Fuente
Docker
Pruebas
Solución de Problemas
Precios
Enlaces
Licencia
Política de Privacidad

Instalación por Cliente

Requisitos

Node.js 22 o posterior
npx disponible en tu terminal
Una clave API de IPGeolocation.io para la mayoría de las herramientas

get_my_ip funciona sin clave API. Todo lo demás requiere una.

Regístrate para obtener una clave API gratuita de IPGeolocation

Codex CLI

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

Inicia una nueva sesión de Codex después de añadir el servidor.

Claude Desktop

Añade a claude_desktop_config.json:

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

Reinicia Claude Desktop después de guardar. También incluimos manifest.json para clientes que admiten MCP Bundles.

Cline

Abre el panel de Servidores MCP > Configurar > Configuración MCP Avanzada. Añade a cline_mcp_settings.json:

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

Reinicia Cline después de guardar.

Cursor

Instalación con un clic:

O añade a .cursor/mcp.json manualmente:

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

Reinicia Cursor después de guardar.

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

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

Reinicia Windsurf después de guardar.

VS Code / GitHub Copilot

Añade a tu settings.json de VS Code:

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

Reinicia VS Code después de guardar.

Glama

Puedes probar el servidor en Glama directamente. Solo se requiere IPGEOLOCATION_API_KEY. Deja los demás campos de variables de entorno vacíos a menos que quieras cambiar el caché, el tiempo de espera o los límites de salida.

Si aún no tienes una clave, crea una clave API gratuita de IPGeolocation.

Cualquier Otro Cliente MCP

Usa esta configuración:

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

Verificar que Funciona

Prueba estos después de la configuración:

Prompt	Herramienta esperada
¿Dónde está 8.8.8.8?	`lookup_ip`
Para la IP 49.12.212.42, dame veredicto de seguridad, empresa, ASN y ciudad.	`lookup_ip` con `fields` y `include=security`
¿Es seguro permitir 2.56.12.11 y cuál es el correo de contacto de abuso?	`lookup_ip` con `include=security,abuse`
Para AS1, lista solo los números de ASN upstream.	`lookup_asn` con `include=upstreams`
Convierte 2026-03-07 09:30 de Nueva York a hora de Tokio.	`convert_timezone`
Dame las horas de amanecer para Karachi del 2026-03-10 al 2026-03-15.	`get_astronomy_time_series`
Analiza 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`

Herramientas por Plan

Plan Gratuito

1,000 créditos por día. Estas 7 herramientas están disponibles:

Herramienta	Créditos	Qué hace
`lookup_ip`	1	Ubicación, zona horaria, moneda, ASN para una IP
`get_my_ip`	0	IP pública de la máquina que ejecuta el servidor
`lookup_currency`	1	Moneda y metadatos de país para una IP
`get_timezone`	1	Zona horaria por nombre, ubicación, IP, código de aeropuerto o UN/LOCODE
`convert_timezone`	1	Convierte la hora entre dos ubicaciones
`get_astronomy`	1	Amanecer, atardecer, salida de luna, puesta de luna, crepúsculo, fase lunar para una fecha
`get_astronomy_time_series`	1	Datos astronómicos diarios para un rango de fechas (hasta 90 días)

Planes de Pago

Las 16 herramientas. Los planes de pago también añaden network, company y campos extendidos de asn a lookup_ip, además del parámetro include para security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code o *.

Herramienta	Créditos	Qué hace
`bulk_lookup_ip`	1 por IP	Geolocalización por lotes, hasta 50,000 IPs (por defecto 1,000)
`check_security`	2	Indicadores de VPN, proxy, Tor, bot, spam y amenazas
`bulk_security_check`	2 por IP	Verificaciones de amenazas por lotes
`lookup_company`	1	Nombre de empresa y titular de ASN para una IP
`lookup_network`	1	Prefijo de ruta, tipo de conexión, estado anycast
`parse_user_agent`	1	Analiza una cadena UA en navegador, dispositivo, SO, motor
`bulk_parse_user_agent`	1 por UA	Análisis de UA por lotes, hasta 50,000 cadenas (por defecto 1,000)
`lookup_asn`	1	Detalles de ASN, peers, upstreams, downstreams, rutas, WHOIS
`get_abuse_contact`	1	Correos de contacto de abuso, teléfono, dirección, ruta

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

Combinación	Créditos totales
Consulta base	1
`include=security`	3
`include=abuse`	2
`include=*`	4
`include=security&fields=security`	2
`include=abuse&fields=abuse`	1

Para detalles actuales del plan y precios, consulta la página de precios de IPGeolocation.

Referencia de Herramientas

lookup_ip

Consulta de una sola IP o dominio. Gratuita y de pago. 1 crédito.

Úsala cuando necesites ubicación, zona horaria, moneda o ASN para una dirección IP. En los planes de pago puedes añadir módulos include para obtener datos de seguridad, abuso o nombre de host en la misma llamada, lo que evita solicitudes adicionales.

El plan gratuito devuelve ubicación base, metadatos de país, moneda, zona horaria y ASN básico. Los planes de pago añaden network, company, ASN extendido y el parámetro include. Ten en cuenta que las consultas de dominio requieren un plan de pago.

Parámetro	Obligatorio	Descripción
`ip`	No	IPv4, IPv6 o dominio. La consulta de dominio requiere un plan de pago.
`lang`	No	Idioma de respuesta. Los idiomas distintos del inglés requieren un plan de pago.
`include`	No	Módulos adicionales: `security`, `abuse`, `hostname`, `liveHostname`, `hostnameFallbackLive`, `user_agent`, `geo_accuracy`, `dma_code` o `*`
`fields`	No	Campos separados por comas a devolver
`excludes`	No	Campos separados por comas a excluir
`force_refresh`	No	Omite el caché y accede directamente a la API

Consejo: combinar include con fields puede reducir tu costo de créditos. Por ejemplo, include=security&fields=security cuesta 2 créditos en lugar de 3 porque omites la respuesta de geolocalización base. De manera similar, include=abuse&fields=abuse cuesta 1 crédito en lugar de 2.

bulk_lookup_ip

Consulta de IP por lotes. De pago. 1 crédito por IP.

Toma un array de IPs o dominios (hasta 1,000 por defecto, configurable con IPGEOLOCATION_MCP_MAX_BULK_ITEMS). Admite las mismas opciones include, fields y excludes que lookup_ip.

Parámetro	Obligatorio	Descripción
`ips`	Sí	Array de direcciones IP o dominios
`lang`	No	Idioma de respuesta
`include`	No	Módulos adicionales por IP
`fields`	No	Campos separados por comas a devolver por IP
`excludes`	No	Campos separados por comas a excluir por IP
`force_refresh`	No	Omite el caché

get_my_ip

Devuelve la IP pública de la máquina que ejecuta el servidor. Gratuita. 0 créditos. No se necesita clave API.

No toma parámetros. Siempre accede a la red (no se almacena en caché). Útil como verificación rápida para confirmar que el proceso del servidor está activo.

check_security

Datos de amenazas y anonimato para una IP. De pago. 2 créditos.

Devuelve puntuación de amenaza, indicadores de VPN/proxy/Tor, nombres de proveedores, puntuaciones de confianza, indicadores de bot/spam, indicadores de anonimato y estado de proveedor de nube.

Si el mismo prompt también solicita ubicación, ASN o datos de abuso, es mejor usar lookup_ip con include=security porque agrupa todo en una sola llamada (3 créditos en total en lugar de 2 + 1 por separado).

Parámetro	Obligatorio	Descripción
`ip`	No	Dirección IP a verificar
`fields`	No	Campos separados por comas a devolver
`excludes`	No	Campos separados por comas a excluir
`force_refresh`	No	Omite el caché

bulk_security_check

Versión por lotes de check_security. De pago. 2 créditos por IP.

Parámetro	Obligatorio	Descripción
`ips`	Sí	Array de direcciones IP
`fields`	No	Campos separados por comas a devolver por IP
`excludes`	No	Campos separados por comas a excluir por IP
`force_refresh`	No	Omite el caché

get_timezone

Hora actual y detalles de zona horaria para una ubicación. Gratuita y de pago. 1 crédito.

Acepta nombres de zona horaria IANA, coordenadas, direcciones IP, códigos de aeropuerto (IATA/ICAO) o UN/LOCODEs. La respuesta incluye desfases de zona horaria, variantes de fecha/fecha-hora, current_time, current_time_unix, time_24, time_12, week, month, year, abreviaturas de zona horaria y detalles de transición de horario de verano.

Siempre accede a la red (no se almacena en caché) porque devuelve la hora actual.

Parámetro	Obligatorio	Descripción
`tz`	No	Nombre de zona horaria IANA (p. ej., `America/New_York`)
`lat` + `long`	No	Latitud y longitud
`location`	No	Cadena de ciudad o dirección
`ip`	No	Dirección IP
`iata_code`	No	Código de aeropuerto IATA
`icao_code`	No	Código de aeropuerto ICAO
`lo_code`	No	UN/LOCODE
`lang`	No	Idioma de respuesta. Los idiomas distintos del inglés requieren un plan de pago.

convert_timezone

Convierte una hora entre dos ubicaciones. Gratuita y de pago. 1 crédito.

Toma los mismos tipos de entrada de ubicación que get_timezone tanto para el origen como para el destino. Si omites el parámetro time, convierte la hora actual. Siempre accede a la red (no se almacena en caché).

Parámetro	Obligatorio	Descripción
`time`	No	`yyyy-MM-dd HH:mm` o `yyyy-MM-dd HH:mm:ss`. Por defecto, ahora.
`tz_from` / `tz_to`	No	Nombres de zona horaria IANA
`lat_from` + `long_from`	No	Coordenadas de origen
`lat_to` + `long_to`	No	Coordenadas de destino
`location_from` / `location_to`	No	Cadenas de ciudad/dirección
`iata_from` / `iata_to`	No	Códigos de aeropuerto IATA
`icao_from` / `icao_to`	No	Códigos de aeropuerto ICAO
`locode_from` / `locode_to`	No	UN/LOCODEs

get_astronomy

Datos de sol y luna para una ubicación en una fecha. Gratuito y de pago. 1 crédito.

Devuelve amanecer, atardecer, salida de la luna, puesta de la luna, crepúsculo matutino y vespertino, mediodía solar, duración del día, fase lunar, indicadores de estado del sol/luna y posición en vivo del sol/luna (altitud, acimut).

Siempre accede a la red (no se almacena en caché) porque omitir date usa por defecto la fecha de hoy.

Parámetro	Obligatorio	Descripción
`lat` + `long`	No	Coordenadas (máxima prioridad cuando se proporcionan)
`location`	No	Ciudad o dirección
`ip`	No	Dirección IP
`date`	No	`YYYY-MM-DD`. Por defecto, hoy.
`elevation`	No	Metros, de 0 a 10000
`time_zone`	No	Nombre IANA para controlar los tiempos de salida
`lang`	No	Idioma de respuesta. El idioma distinto del inglés requiere un plan de pago.

get_astronomy_time_series

Datos de astronomía para un rango de fechas, hasta 90 días. Gratuito y de pago. 1 crédito por solicitud.

Cada entrada diaria incluye mid_night, night_end, morning, sunrise, sunset, evening, night_begin, sun_status, solar_noon, day_length, moon_phase, moonrise, moonset y moon_status. Use esto en lugar de llamar a get_astronomy repetidamente para un rango.

Parámetro	Obligatorio	Descripción
`dateStart`	Sí	Fecha de inicio (`YYYY-MM-DD`)
`dateEnd`	Sí	Fecha de fin (`YYYY-MM-DD`). Máximo: 90 días.
`lat` + `long`	No	Coordenadas (máxima prioridad cuando se proporcionan)
`location`	No	Ciudad o dirección
`ip`	No	Dirección IP
`elevation`	No	Metros
`time_zone`	No	Nombre IANA para controlar los tiempos de salida
`lang`	No	Idioma de respuesta. El idioma distinto del inglés requiere un plan de pago.
`force_refresh`	No	Omitir la caché

parse_user_agent

Analiza una cadena UA en datos de navegador, dispositivo, SO y motor. De pago. 1 crédito.

También clasifica bots y rastreadores. Nota: esto analiza el uaString que usted proporciona. No infiere un UA de llamada desde la propia conexión MCP.

Parámetro	Obligatorio	Descripción
`uaString`	Sí	La cadena de user-agent a analizar
`force_refresh`	No	Omitir la caché

Devuelve name, type, version, device, engine y operating_system.

bulk_parse_user_agent

Versión por lotes de parse_user_agent. De pago. 1 crédito por cadena.

Acepta hasta 1,000 cadenas por solicitud por defecto (configurable con IPGEOLOCATION_MCP_MAX_BULK_ITEMS).

Parámetro	Obligatorio	Descripción
`uaStrings`	Sí	Matriz de cadenas de user-agent
`force_refresh`	No	Omitir la caché

lookup_company

Devuelve solo el nombre de la empresa y el titular del ASN para una IP. De pago. 1 crédito.

Devuelve objetos company y asn. lookup_ip devuelve los mismos datos más ubicación, zona horaria y más. Use esto cuando el par empresa/ASN sea todo lo que necesita y desee una respuesta más pequeña.

Parámetro	Obligatorio	Descripción
`ip`	No	Dirección IP
`force_refresh`	No	Omitir la caché

lookup_currency

Moneda, código de llamada del país, TLD e idiomas para una IP. Gratuito y de pago. 1 crédito.

Devuelve objetos currency y country_metadata.

Parámetro	Obligatorio	Descripción
`ip`	No	Dirección IP
`force_refresh`	No	Omitir la caché

lookup_network

Prefijo de ruta, tipo de conexión y estado anycast para una IP. De pago. 1 crédito.

Devuelve un objeto network con connection_type, route y is_anycast.

Parámetro	Obligatorio	Descripción
`ip`	No	Dirección IP
`force_refresh`	No	Omitir la caché

lookup_asn

Búsqueda completa de ASN. De pago. 1 crédito.

lookup_ip también devuelve un objeto asn, pero solo con metadatos básicos. Esta herramienta devuelve el registro ASN completo, incluidos pares, upstreams, downstreams, rutas y WHOIS. Llámela una vez con los campos include que necesite y luego filtre localmente en lugar de hacer múltiples llamadas para diferentes secciones.

Parámetro	Obligatorio	Descripción
`asn`	No	ASN (p. ej., `AS13335` o `13335`)
`ip`	No	Dirección IP para resolver a un ASN
`include`	No	`peers`, `downstreams`, `upstreams`, `routes`, `whois_response`
`fields`	No	Campos separados por comas a devolver
`excludes`	No	Campos separados por comas a excluir
`force_refresh`	No	Omitir la caché

get_abuse_contact

Detalles de contacto de abuso para una IP. De pago. 1 crédito.

Devuelve la ruta de abuso, país, nombre de contacto, organización, dirección, direcciones de correo electrónico y números de teléfono. Si también necesita datos de geolocalización o seguridad para la misma IP, use lookup_ip con include=abuse (o include=security,abuse) para obtener todo en una sola llamada.

Parámetro	Obligatorio	Descripción
`ip`	No	Dirección IP
`fields`	No	Campos separados por comas a devolver
`excludes`	No	Campos separados por comas a excluir
`force_refresh`	No	Omitir la caché

Ejemplos de Prompts

Comprobar si una IP es segura

¿Es 49.12.212.42 segura para confiar en nuestra red? Dame el resumen de amenazas y la ciudad.
Comprueba estas IPs en busca de indicadores de VPN, proxy, Tor, bot y spam: 49.12.212.42, 2.56.12.11, 8.8.8.8
Para 203.0.113.42, dime la puntuación de amenaza, si es un proveedor de nube y si parece un relay.

Encontrar quién es el propietario de una IP

¿Quién usa 1.1.1.1 y qué ASN la enruta?
Para AS24940, lista solo los números de ASN upstream.
¿Es esta IP anycast y qué prefijo de ruta se anuncia para ella: 1.1.1.1

Obtener contactos de abuso

Para la IP 2.56.12.11, dame el correo electrónico de contacto de abuso, el número de teléfono y la organización.
Necesito el contacto de abuso para 1.0.0.0 y la ruta de red involucrada.
Para esta IP, muéstrame solo los detalles de contacto de abuso: 198.51.100.27

Búsquedas y conversiones de zona horaria

¿Qué hora es ahora en Tokio?
Convierte 2026-03-07 09:30 de Nueva York a hora de Tokio.
¿Cuál es la hora local actual en el aeropuerto JFK?

Datos de amanecer, atardecer y luna

Dame el amanecer y el atardecer para Londres el 2026-06-21.
Muestra los horarios de amanecer en Karachi del 2026-03-10 al 2026-03-15.
Para Nueva York, dame la fase lunar y la duración del día el 2026-07-17.

Analizar cadenas de user-agent

Analiza 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
Analiza estos user agents en lote y dime el navegador, SO y tipo de dispositivo para cada uno.
¿Este user agent parece un rastreador o 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)

Ejemplos de Respuestas y Salida de Herramientas

Las respuestas de texto a continuación muestran lo que un cliente podría decir. La redacción exacta depende del modelo. Los bloques JSON muestran la salida bruta de la herramienta, recortada para facilitar la lectura.

Búsqueda de IP individual

Solicitud: Localiza 91.128.103.196 y dame el país, la ciudad, el ASN y la hora local.

Ejemplo de respuesta: 91.128.103.196 está en Estocolmo, Suecia. El ASN es AS1257, operado por Tele2 Sverige AB. La zona horaria es Europe/Stockholm, la 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"
  }
}

Conversión de hora

Solicitud: Convierte 2025-01-21 13:42:52 de DXB a LHR.

Ejemplo de respuesta: 2025-01-21 13:42:52 en Dubái se convierte a 2025-01-21 09:42:52 en Londres. La diferencia es 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
}

Contacto de abuso

Solicitud: Dame el contacto de abuso para 1.0.0.0.

Ejemplo de respuesta: El contacto de abuso para 1.0.0.0 es IRT-APNICRANDNET-AU en Australia, que cubre la ruta 1.0.0.0/24. Correo electrónico: 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 Error

Todas las herramientas devuelven errores estructurados en lugar de bloquear el servidor. Los errores de API incluyen el estado/mensaje upstream más un campo guidance para que los clientes MCP puedan indicar al usuario qué comprobar a continuación en lugar de solo repetir la respuesta upstream.

Código	Significado
`400`	Parámetros incorrectos, formato de fecha/hora no válido, par de coordenadas faltante o entrada no compatible
`401`	Clave de API faltante/no válida, plan gratuito llamando a una herramienta de pago, o `lang` distinto del inglés en el plan gratuito
`404`	Recurso no encontrado (p. ej., el ASN no existe)
`405`	Restricción de método o suscripción de la API upstream
`413`	El cuerpo POST es más grande de lo que permite la API upstream
`415`	La solicitud POST no tiene el tipo de contenido `application/json` requerido
`423`	IP bogon o privada (`10.x.x.x`, `192.168.x.x`, etc.)
`429`	Límite diario de solicitudes (plan gratuito) o cuota de suscripción/recargo excedida
`499`	El tiempo de espera de solicitud o conexión del lado del cliente fue demasiado corto
`5xx`	Error del lado del servidor de la API upstream
`502`	El servidor no pudo alcanzar la API upstream
`504`	La API upstream agotó el tiempo de espera

Los códigos de estado exactos pueden variar según el endpoint y el modo de solicitud. Si un endpoint upstream devuelve un estado fuera de esta tabla, el servidor no adivina la causa. Transmite el estado y mensaje upstream con category: "undocumented_api_error" y añade orientación para que el cliente MCP explique la respuesta como un estado upstream no documentado sin inventar una causa.

Cómo Funciona

Este es un servidor MCP stdio que envuelve las APIs v3 de ipgeolocation.io.

En tiempo de ejecución:

Su cliente MCP inicia el proceso del servidor.
El cliente lee la lista de herramientas.
Cuando una solicitud coincide con una herramienta, el cliente la llama.
El servidor valida las entradas, llama a nuestra API y devuelve JSON estructurado.
Las respuestas almacenables en caché se guardan en la memoria del proceso para que las solicitudes idénticas repetidas omitan la llamada a la API.

Las solicitudes upstream autenticadas envían la clave de API en el encabezado x-ipgeolocation-api-key. La clave no se añade a las URL de solicitud.

lookup_company, lookup_currency y lookup_network son envoltorios alrededor de partes de la respuesta completa de búsqueda de IP. Existen como herramientas separadas para que los clientes MCP puedan descubrirlas cuando un usuario solo necesita un dato.

Almacenamiento en Caché

Las herramientas que devuelven datos estables (no búsquedas de hora actual) almacenan sus respuestas en la memoria del proceso. Las búsquedas repetidas son más rápidas y no usan créditos adicionales. Los reintentos del cliente no generan llamadas API duplicadas.

Caché a nivel de proceso, no memoria de cliente o modelo
Las entradas de caché están limitadas por clave de API, por lo que las sesiones MCP separadas no comparten datos upstream almacenados en caché
TTL predeterminado: 5 minutos (300000 ms)
La caché se restablece cuando se detiene el proceso del servidor
La caché falla al expirar el TTL, cambiar los parámetros o force_refresh: true En caché: 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

Siempre en vivo (no en caché): get_my_ip, get_timezone, convert_timezone, get_astronomy

Variables de Entorno

Variable	Requerido	Por defecto	Descripción
`IPGEOLOCATION_API_KEY`	Sí (la mayoría de las herramientas)		Tu clave API de ipgeolocation.io
`IPGEOLOCATION_REQUEST_TIMEOUT_MS`	No	`15000`	Tiempo de espera del upstream en ms. Rango: 1000-120000
`IPGEOLOCATION_MCP_CACHE_TTL_MS`	No	`300000`	TTL de caché en ms. Rango: 1000-3600000
`IPGEOLOCATION_MCP_CACHE_MAX_ENTRIES`	No	`500`	Máximo de entradas antes de la expulsión. Rango: 10-5000
`IPGEOLOCATION_MCP_MAX_BULK_ITEMS`	No	`1000`	Máximo de elementos por solicitud masiva. Máx: 50000
`IPGEOLOCATION_MCP_MAX_RESULT_ITEMS`	No	`250`	Máximo de elementos de array antes de la truncación
`IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS`	No	`200000`	Longitud máxima del texto de respuesta
`IPGEOLOCATION_MCP_MAX_ERROR_CHARS`	No	`4000`	Longitud máxima del texto de error

Compilación desde el Código Fuente

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

Ejecútalo directamente:

IPGEOLOCATION_API_KEY=<YOUR_KEY> node dist/cli.js

Inspecciona con 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

Pruebas

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

Solución de Problemas

El cliente usa una herramienta antigua después de actualizar: Reinicia el cliente y confirma que cargó la última versión de npm.

Errores 401: Verifica que IPGEOLOCATION_API_KEY esté configurado en tu configuración. Algunas herramientas son solo de pago y devuelven 401 en el plan gratuito. Las búsquedas de dominios en lookup_ip también requieren un plan de pago.

Errores 423: Pasaste una IP privada/bogon como 10.0.0.1 o 192.168.1.1. Estas no tienen datos de geolocalización.

Tiempos de espera 504: La API upstream no respondió a tiempo. Aumenta el tiempo de espera con IPGEOLOCATION_REQUEST_TIMEOUT_MS (por defecto: 15000 ms, máximo: 120000 ms).

Precios

Para detalles actuales del plan, créditos y precios, consulta la página de precios de IPGeolocation.