MCP Server IPGeolocation.io

Официальный MCP Server от IPGeolocation.io предоставляет 17 инструментов для точного определения геолокации IP-адресов, получения информации о компаниях, данных ASN и сети, проверки безопасности IP (обнаружение VPN, proxy, Tor, ботов, хостинга и спама), поиска контактов для сообщений о злоупотреблениях, а также работы с часовыми поясами, астрономическими и валютными данными и разбора user-agent.

MCP (Model Context Protocol) подключает ваш клиент к этим инструментам. Клиент или хост должен поддерживать запуск локальной команды через stdio. Примеры настройки см. в разделе «Установка для конкретного клиента».

В этом README описана версия 2.0.1. Команды npx и ссылка для установки в Cursor ниже используют тег npm latest, который будет указывать и на будущие основные версии. Чтобы загрузить обновление, перезапустите сервер. npm повторно использует кэшированные файлы пакета, если выбранная версия не изменилась. Подробности о выпусках см. в журнале изменений.

Параметр	Значение
Пакет	ipgeolocation-io-mcp
Версия	2.0.1
Дата выпуска	2026-10-11
Транспорт	stdio
Node.js	>=22

Быстрый старт

• Создайте бесплатный API key IPGeolocation.

• Добавьте эту запись в личную конфигурацию клиента, сохранив настройки существующих серверов. Расположение файла конфигурации см. в разделе «Установка для конкретного клиента». В Cursor также доступна установка в один клик.

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

• Перезагрузите сервер или перезапустите клиент.

• Спросите: «Где находится 8.8.8.8?»

Содержание

• Быстрый старт

• Установка для конкретного клиента

• Проверка работы

• Инструменты в зависимости от плана

• Справочник по инструментам

• Примеры запросов

• Примеры ответов и результатов работы инструментов

• Коды ошибок

• Принцип работы

• Кэширование

• Постраничная навигация по кэшированным результатам

• Переменные среды

• Сборка из исходного кода

• Docker

• Тестирование

• Устранение неполадок

• Цены

• Ссылки

• Лицензия

• Политика конфиденциальности

Установка для конкретного клиента

Требования

• Node.js 22 или новее для установки через npm или из исходного кода либо хост с совместимой средой выполнения Node.js

• Для примеров конфигурации npm должна быть доступна команда npx

• Для работы большинства инструментов API требуется API key IPGeolocation.io

Используйте поддерживаемый выпуск Node.js с последними обновлениями безопасности.

Для get_my_ip API key не требуется. Для остальных 15 инструментов API он необходим. get_cached_result считывает результаты, уже сохранённые в памяти; используйте тот же API key, что и для исходного запроса.

Зарегистрируйтесь и получите бесплатный API key IPGeolocation

Для настоящего ключа используйте личную конфигурацию пользователя либо настройки секретов или переменных среды клиента. Не сохраняйте ключи в конфигурации проекта, добавляемой в репозиторий. Для каждого клиента ниже используется запись сервера из раздела «Быстрый старт», если не указано иное.

Codex CLI

Перед выполнением этих команд задайте IPGEOLOCATION_API_KEY в личной среде оболочки. Подстановка переменной позволяет не указывать значение ключа непосредственно в команде и не сохранять его в истории оболочки.

codex mcp add ipgeolocation --env "IPGEOLOCATION_API_KEY=$IPGEOLOCATION_API_KEY" -- npx -y ipgeolocation-io-mcp@latest
codex mcp list

После добавления сервера запустите новую сессию Codex.

Claude Desktop

Установите опубликованный сервер со страницы Claude Marketplace. В Claude Desktop откройте Settings > Extensions > Browse extensions, найдите IPGeolocation.io MCP Server и укажите API key при установке. Инструкции см. в руководстве Anthropic по расширениям для настольного приложения. В каталоге размещён одобренный опубликованный пакет, обновление которого может выходить позже, чем релизы на GitHub. Проверьте установленную версию или скачайте пакет нужной версии по ссылке ниже.

Чтобы настроить npm вручную, откройте в Claude Desktop Settings > Developer > Edit Config. Откроется файл claude_desktop_config.json:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте запись из раздела «Быстрый старт» в mcpServers.

После сохранения полностью закройте и снова откройте Claude Desktop. См. официальное руководство по настройке локального сервера.

Для клиентов, устанавливающих MCP Bundles, скачайте опубликованный пакет .mcpb версии 2.0.1 со страницы GitHub Releases. Пакет содержит сервер и его зависимости; для работы хоста по-прежнему нужна среда выполнения Node.js 22 или новее. Введите API key, когда хост запросит настройки пакета.

Cline

В Cline откройте MCP Servers > Configure > Configure MCP Servers. Добавьте запись из раздела «Быстрый старт» в mcpServers файла JSON с настройками. По умолчанию Cline CLI использует файл ~/.cline/data/settings/cline_mcp_settings.json. Подробнее см. в руководстве Cline по MCP.

После сохранения перезапустите Cline.

Cursor

Установка в один клик:

Или добавьте настройки в .cursor/mcp.json для текущего проекта либо в ~/.cursor/mcp.json для всех проектов. См. руководство Cursor по MCP.

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

После сохранения перезапустите Cursor.

Плагин Cursor

В этом репозитории есть плагин Cursor для ipgeolocation-io-mcp. Он работает локально через stdio и требует Node.js 22 или новее.

Чтобы установить плагин локально, клонируйте этот репозиторий в новую директорию внутри ~/.cursor/plugins/local/, перезагрузите Cursor и откройте Customize > Plugins.

• Локальный плагин: задайте IPGEOLOCATION_API_KEY в среде, из которой запускается Cursor. Плагин получает ключ из этой среды.

• Установка из Marketplace: задайте ключ в личной конфигурации плагина.

Если API key не задан или его значение пустое, get_my_ip продолжит работать. Инструменты API, которым нужен ключ, вернут ошибку об отсутствующем ключе и не будут отправлять запрос.

Чтобы загрузить локальную копию репозитория через Cursor CLI:

agent --plugin-dir /absolute/path/to/ipgeolocation-io-mcp

Для API-запросов, требующих ключа, используются тарифный план и кредиты вашей учётной записи. Инструмент get_cached_result считывает сохранённые страницы ответов, не отправляя повторный API-запрос.

Установите этот сервер только одним способом: иначе в списке появятся дублирующиеся инструменты. Другие серверы можно оставить в существующей конфигурации.

Windsurf / Cascade

В Cascade откройте меню ... (Actions) и выберите Open MCP config file в разделе MCPs. Добавьте запись из раздела «Быстрый старт» в файл, открытый вашей версией клиента: пути к конфигурации различаются в зависимости от выпуска. В новых версиях сведения об активном агенте и расположении конфигурации приведены в руководстве поставщика по MCP для Cascade.

Сохраните файл и перезагрузите сервер в клиенте.

Kiro Powers

Power для Kiro предоставляет 17 инструментов для определения геолокации IP-адресов, получения информации о компаниях, данных ASN и сети, проверки безопасности IP (обнаружение VPN, proxy, Tor, ботов, хостинга и спама), поиска контактов для сообщений о злоупотреблениях, а также работы с часовыми поясами, астрономическими и валютными данными и разбора user-agent. Он запускает ipgeolocation-io-mcp локально через stdio, использует тег npm latest и требует Node.js 22 или новее. Импортируйте папку packaging/kiro через Powers > Add Custom Power и следуйте инструкциям по настройке личного API key. Для большинства инструментов нужен ключ; доступность инструментов и количество кредитов зависят от вашего плана.

VS Code / GitHub Copilot

Вызовите команду MCP: Add Server из палитры команд, выберите локальную команду и укажите npx -y ipgeolocation-io-mcp@latest. Выберите Copilot Global, чтобы сохранить настройки в личной конфигурации, или .mcp.json — для переносимой конфигурации рабочей области. Добавьте IPGEOLOCATION_API_KEY в среду сервера.

В переносимом формате .mcp.json используется объект верхнего уровня mcpServers, показанный в разделе «Быстрый старт».

Запустите сервер с помощью действия Start и подтвердите его настройки, когда появится запрос. В существующих файлах .vscode/mcp.json используется объект верхнего уровня servers. Подробнее см. в руководстве VS Code по настройке MCP.

Glama

Попробовать сервер можно непосредственно на Glama. Требуется только IPGEOLOCATION_API_KEY. Остальные поля переменных среды оставьте пустыми, если не хотите менять параметры кэша, тайм-аута или ограничений вывода.

Если у вас ещё нет ключа, создайте бесплатный API key IPGeolocation.

Другие MCP-клиенты

Используйте запись сервера ipgeolocation из раздела Quick Start в формате конфигурации вашего клиента. Клиент должен поддерживать запуск локального процесса stdio. Если клиент принимает только удалённый URL MCP, потребуется размещённая конечная точка: этот пакет предоставляет команду запуска сервера.

Проверка работы

После настройки попробуйте выполнить следующие запросы:

Запрос	Ожидаемый инструмент
Где находится адрес 8.8.8.8?	lookup_ip
Для IP-адреса 49.12.212.42 укажите признаки угроз, компанию, ASN и город.	lookup_ip с параметрами fields и include=security
Покажите признаки угроз и контактный адрес электронной почты для сообщений о злоупотреблениях для адреса 2.56.12.11.	lookup_ip с параметром include=security,abuse
Для AS1 перечислите только номера вышестоящих ASN.	lookup_asn с параметром include=upstreams
Переведите время 2026-03-07 09:30 из Нью-Йорка в Токио.	convert_timezone
Укажите время восхода солнца в Карачи с 2026-03-10 по 2026-03-15.	get_astronomy_time_series
Разберите эту строку 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

Инструменты по тарифным планам

В версии 2.0.1 доступны 16 инструментов API и get_cached_result — средство чтения страниц из кэша, не расходующее кредиты. По умолчанию инструменты пакетной обработки принимают до 250 элементов; фактический предел определяется меньшим из двух настроенных лимитов.

Указанная стоимость применяется к успешным запросам к вышестоящему API. Обращения к кэшу и чтение закэшированных страниц не расходуют дополнительные кредиты. Фактическое списание указывается в заголовке ответа API X-Credits-Charged; подробности приведены в правилах использования кредитов.

Бесплатный тарифный план

1 000 кредитов в день. Эти 7 инструментов API предоставляют основные данные, описанные в документации; инструмент get_cached_result также читает ранее возвращённые страницы без расхода кредитов:

Инструмент	Кредиты	Назначение
lookup_ip	1	Местоположение, часовой пояс, валюта и ASN для одного IP-адреса
get_my_ip	0	Публичный IP-адрес компьютера, на котором запущен сервер
lookup_currency	1	Валюта и сведения о стране для одного IP-адреса
get_timezone	1	Часовой пояс по названию, местоположению, IP-адресу, коду аэропорта или UN/LOCODE
convert_timezone	1	Перевод времени между двумя местоположениями
get_astronomy	1	Время восхода и захода солнца, восхода и захода Луны, сумерек, а также фаза Луны для одной даты
get_astronomy_time_series	1	Ежедневные астрономические данные за диапазон дат продолжительностью до 90 дней

На бесплатных тарифных планах lookup_company также возвращает основные сведения о владельце ASN, но не данные о компании. Если API не предоставляет платные сетевые данные, lookup_network возвращает локальную ошибку. В документации API пакетное определение геолокации указано как доступное только на платных тарифах; однако при проверке с ключом бесплатного тарифа API также возвращал основные пакетные результаты. Доступность функций определяется на стороне API, поэтому не следует считать пакетную обработку доступной на бесплатном тарифе, опираясь только на это наблюдение.

Платные тарифные планы

Доступны все 17 инструментов, включая средство чтения кэшированных результатов, не расходующее кредиты. На платных тарифных планах в lookup_ip также доступны поля network, company и расширенные поля asn, а параметр include позволяет запрашивать security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code или *.

Инструмент	Кредиты	Назначение
bulk_lookup_ip	1 за IP-адрес	Пакетное определение геолокации; по умолчанию — до 250 элементов
check_security	2	Признаки VPN, прокси, Tor, ботов, спама и угроз
bulk_security_check	2 за IP-адрес	Пакетная проверка угроз
lookup_company	1	Название компании и владелец ASN для одного IP-адреса
lookup_network	1	Префикс маршрута, тип подключения и статус anycast
parse_user_agent	1	Разбор одной строки UA: браузер, устройство, ОС и движок
bulk_parse_user_agent	1 за UA	Пакетный разбор UA; по умолчанию — до 250 строк
lookup_asn	1	Сведения об ASN, узлы равноправного обмена, вышестоящие и нижестоящие ASN, маршруты и WHOIS
get_abuse_contact	1	Адреса электронной почты, телефон и адрес для сообщений о злоупотреблениях, а также маршрут

Расчёт стоимости lookup_ip с параметром include:

Комбинация	Всего кредитов
Базовый запрос	1
include=security	3
include=abuse	2
include=*	4
include=security&fields=security	2
include=abuse&fields=abuse	1

Актуальные сведения о тарифах и стоимости приведены на странице тарифов IPGeolocation.

Справочник по инструментам

Аргументы инструментов должны соответствовать объявленной схеме. Неизвестные параметры отклоняются локально до отправки запроса к API, поэтому опечатка в селекторе не приведёт к незаметному поиску IP-адреса сервера.

Координаты, в том числе селекторы преобразования, и elevation должны передаваться в виде строк, например "24.86" и "10". Для force_refresh требуется логическое значение.

lookup_ip

Поиск данных для одного IP-адреса или домена через API IP Geolocation. Бесплатно и платно. Базовые данные об IP-адресе стоят 1 кредит.

Используйте этот инструмент, чтобы получить местоположение, часовой пояс, валюту или ASN для одного IP-адреса. На платных тарифных планах можно добавить модули include для получения данных о безопасности, злоупотреблениях или имени хоста в том же запросе, не отправляя дополнительные запросы.

Бесплатный тарифный план предоставляет основные данные о местоположении, сведения о стране, валюту, часовой пояс и базовую информацию об ASN. На платных тарифных планах доступны network, company, расширенные данные ASN и параметр include. Обратите внимание: поиск по домену доступен только на платном тарифном плане.

Параметр	Обязательный	Описание
ip	Нет	IPv4, IPv6 или домен. Поиск по домену доступен только на платном тарифном плане.
lang	Нет	Язык ответа. Языки, отличные от английского, доступны только на платном тарифном плане.
include	Нет	Дополнительные модули: security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code или *
fields	Нет	Список возвращаемых полей через запятую
excludes	Нет	Список исключаемых полей через запятую
force_refresh	Нет	Пропустить кэш и напрямую обратиться к API

Совет: сочетание include и fields может снизить расход кредитов. Например, include=security&fields=security стоит 2 кредита вместо 3, поскольку базовые данные о геолокации не запрашиваются. Аналогично, include=abuse&fields=abuse стоит 1 кредит вместо 2.

Выбранные поля подключают необходимые для них дополнительные модули. Для следующих модулей требуется платный тарифный план:

Выбранное поле	Подключаемый модуль
security.is_vpn	security
location.accuracy_radius, location.confidence или location.locality	geo_accuracy
location.dma_code	dma_code

Данные о точности и DMA находятся в разделе location. Если модуль явно указан в include, он останется в ответе, даже если отсутствует в fields. Можно исключать вложенные поля, однако корневой раздел, указанный в fields или явно включённый через include, останется в ответе. Параметр include=* учитывает выбор полей и исключения, но не гарантирует сохранение этих корневых разделов. Для кэшированных результатов действуют те же правила, что и для новых ответов.

bulk_lookup_ip

Пакетный поиск IP-адресов. Платно. 1 кредит за IP-адрес.

Принимает массив IP-адресов или доменов (по умолчанию — до 250 элементов). Пакетный лимит определяется меньшим из значений IPGEOLOCATION_MCP_MAX_BULK_ITEMS и IPGEOLOCATION_MCP_MAX_RESULT_ITEMS. Поддерживает те же параметры include, fields и excludes, что и lookup_ip.

Параметр	Обязательный	Описание
ips	Да	Массив IP-адресов или доменов
lang	Нет	Язык ответа
include	Нет	Дополнительные модули для каждого IP-адреса
fields	Нет	Список возвращаемых полей для каждого IP-адреса через запятую
excludes	Нет	Список исключаемых полей для каждого IP-адреса через запятую
force_refresh	Нет	Пропустить кэш

get_my_ip

Возвращает публичный IP-адрес компьютера, на котором запущен сервер. Бесплатно. 0 кредитов. API-ключ не требуется.

Параметры не принимает. Всегда обращается к сети, не используя кэш. Этот инструмент удобно использовать для быстрой проверки, что процесс сервера работает.

check_security

Данные об угрозах и анонимности для одного IP-адреса через API IP Security. Платно. 2 кредита.

Возвращает оценку угроз, признаки VPN, прокси и Tor, названия провайдеров, оценки достоверности, признаки ботов и спама, признаки анонимности, а также сведения о статусе облачного провайдера.

Если в том же запросе нужны местоположение или ASN, используйте lookup_ip с параметром include=security, чтобы получить эти сведения одним запросом. Это стоит 3 кредита — столько же, сколько отдельная проверка безопасности и базовый поиск. Если нужны также контакты для сообщений о злоупотреблениях, добавьте abuse в параметр include.

Параметр	Обязательный	Описание
ip	Нет	IP-адрес для проверки
fields	Нет	Список возвращаемых полей через запятую
excludes	Нет	Список исключаемых полей через запятую
force_refresh	Нет	Пропустить кэш

bulk_security_check

Пакетный вариант check_security. Платно. 2 кредита за IP-адрес. По умолчанию принимает до 250 элементов с учётом тех же ограничений пакетной обработки, что и bulk_lookup_ip.

Параметр	Обязательный	Описание
ips	Да	Массив IP-адресов
fields	Нет	Список возвращаемых полей для каждого IP-адреса через запятую
excludes	Нет	Список исключаемых полей для каждого IP-адреса через запятую
force_refresh	Нет	Пропустить кэш

get_timezone

Текущее время и сведения о часовом поясе для указанного местоположения через Time Zone API. Доступен на бесплатном и платном тарифах. 1 кредит.

Принимает названия часовых поясов IANA, координаты, IP-адреса, коды аэропортов (IATA/ICAO) и коды UN/LOCODE. В ответе содержатся смещения часового пояса, варианты даты и даты-времени, current_time, current_time_unix, time_24, time_12, week, month, year, сокращённые названия часовых поясов и сведения о переходах на летнее время.

Если не указать параметр для выбора местоположения, API использует публичный внешний IP-адрес сервера, который может отличаться от вашего IP-адреса.

Каждый вызов обращается к сети и не использует кэш, поскольку возвращает текущее время.

Параметр	Обязательный	Описание
tz	Нет	Название часового пояса IANA (например, America/New_York)
lat + long	Нет	Широта и долгота
location	Нет	Название города или адрес
ip	Нет	IP-адрес
iata_code	Нет	Код аэропорта IATA
icao_code	Нет	Код аэропорта ICAO
lo_code	Нет	Код UN/LOCODE
lang	Нет	Язык ответа. Для языков, отличных от английского, нужен платный тариф.

convert_timezone

Преобразует время между двумя местоположениями. Доступен на бесплатном и платном тарифах. 1 кредит.

Укажите один параметр для исходного местоположения и один — для целевого. Можно использовать часовой пояс IANA, координаты, название города или адрес, код аэропорта либо код UN/LOCODE. Если не указать time, API преобразует текущее время. Инструмент не принимает IP-адреса в качестве параметров местоположения и не поддерживает lang. Каждый вызов обращается к API и не использует кэш.

Параметр	Обязательный	Описание
time	Нет	yyyy-MM-dd HH:mm или yyyy-MM-dd HH:mm:ss. По умолчанию используется текущее время.
tz_from / tz_to	Нет	Названия часовых поясов IANA
lat_from + long_from	Нет	Координаты исходного местоположения
lat_to + long_to	Нет	Координаты целевого местоположения
location_from / location_to	Нет	Названия городов или адреса
iata_from / iata_to	Нет	Коды аэропортов IATA
icao_from / icao_to	Нет	Коды аэропортов ICAO
locode_from / locode_to	Нет	Коды UN/LOCODE

get_astronomy

Сведения о солнце и луне для одного местоположения на выбранную дату через Astronomy API. Доступен на бесплатном и платном тарифах. 1 кредит.

Возвращает время восхода и захода солнца и луны, начало утренних и вечерних сумерек, солнечный полдень, продолжительность дня, фазу луны, флаги состояния солнца и луны, а также их текущее положение (высоту над горизонтом и азимут).

Инструмент всегда обращается к API, даже если указан параметр date; кэширование ответа не используется.

Параметр	Обязательный	Описание
lat + long	Нет	Координаты (имеют наивысший приоритет, если указаны)
location	Нет	Название города или адрес
ip	Нет	IP-адрес
date	Нет	YYYY-MM-DD. По умолчанию используется сегодняшняя дата.
elevation	Нет	Высота в метрах, от 0 до 10000
time_zone	Нет	Название часового пояса IANA для форматирования времени в ответе
lang	Нет	Язык ответа. Для языков, отличных от английского, нужен платный тариф.

get_astronomy_time_series

Астрономические данные за указанный период продолжительностью до 90 дней. Доступен на бесплатном и платном тарифах. 1 кредит за запрос.

Для каждого дня возвращаются поля mid_night, night_end, morning, sunrise, sunset, evening, night_begin, sun_status, solar_noon, day_length, moon_phase, moonrise, moonset и moon_status. Используйте этот инструмент вместо многократных вызовов get_astronomy для получения данных за период.

Параметр	Обязательный	Описание
dateStart	Да	Начальная дата (YYYY-MM-DD)
dateEnd	Да	Конечная дата (YYYY-MM-DD). Максимальная продолжительность периода — 90 дней.
lat + long	Нет	Координаты (имеют наивысший приоритет, если указаны)
location	Нет	Название города или адрес
ip	Нет	IP-адрес
elevation	Нет	Высота в метрах
time_zone	Нет	Название часового пояса IANA для форматирования времени в ответе
lang	Нет	Язык ответа. Для языков, отличных от английского, нужен платный тариф.
force_refresh	Нет	Обойти кэш

parse_user_agent

Разбирает одну строку UA и возвращает сведения о браузере, устройстве, ОС и движке через User-Agent API. Платный тариф. 1 кредит.

Также определяет, является ли UA ботом или поисковым роботом. Обратите внимание: инструмент анализирует переданную вами строку uaString. Он не определяет UA вызывающей стороны по самому подключению MCP.

Параметр	Обязательный	Описание
uaString	Да	Строка user-agent для анализа
force_refresh	Нет	Обойти кэш

Возвращает поля name, type, version, device, engine и operating_system.

bulk_parse_user_agent

Пакетная версия parse_user_agent. Платный тариф. 1 кредит за строку.

По умолчанию принимает до 250 строк за запрос. Максимальный размер пакета определяется меньшим из значений IPGEOLOCATION_MCP_MAX_BULK_ITEMS и IPGEOLOCATION_MCP_MAX_RESULT_ITEMS.

Параметр	Обязательный	Описание
uaStrings	Да	Массив строк user-agent
force_refresh	Нет	Обойти кэш

lookup_company

Сведения о компании и владельце ASN для одного IP-адреса. Сведения о компании доступны на платном тарифе; на бесплатном тарифе возвращаются только базовые данные ASN. 1 кредит.

Возвращает объекты company и asn. Инструмент lookup_ip возвращает те же данные, а также местоположение, часовой пояс и другие сведения. Используйте этот инструмент, если вам нужны только данные о компании и ASN и вы хотите получить более компактный ответ.

Параметр	Обязательный	Описание
ip	Нет	IP-адрес
force_refresh	Нет	Обойти кэш

lookup_currency

Сведения о валюте, телефонном коде страны, TLD и языках для одного IP-адреса. Доступен на бесплатном и платном тарифах. 1 кредит.

Возвращает объекты currency и country_metadata.

Параметр	Обязательный	Описание
ip	Нет	IP-адрес
force_refresh	Нет	Обойти кэш

lookup_network

Префикс маршрута, тип подключения и сведения о статусе anycast для одного IP-адреса. Платный тариф. 1 кредит.

Возвращает объект network с полями connection_type, route и is_anycast. Если API не возвращает сетевые данные, инструмент выдаёт локальную ошибку, а не пустой успешный ответ. При этом он не подставляет несуществующий HTTP-статус вышестоящего сервиса, а вызов API уже мог списать кредиты.

Параметр	Обязательный	Описание
ip	Нет	IP-адрес
force_refresh	Нет	Обойти кэш

lookup_asn

Сведения о распределении сетевых ресурсов и связях через ASN API. Платный тариф. 1 кредит.

Используйте этот инструмент для получения сведений об ASN, а также при необходимости — данных о пирах, вышестоящих и нижестоящих сетях, маршрутах и WHOIS. Укажите нужные наборы данных в параметре include, а затем фильтруйте кэшированный результат, чтобы получать разные выборки. Инструмент lookup_ip также возвращает метаданные ASN в составе сведений об IP-адресе.

Параметр fields автоматически включает дополнительные наборы данных, на которые он ссылается, например upstreams.as_number. Сам по себе параметр excludes не запрашивает дополнительные наборы данных.

Параметр	Обязательный	Описание
asn	Нет	ASN (например, AS13335 или 13335)
ip	Нет	IP-адрес для определения ASN
include	Нет	peers, downstreams, upstreams, routes, whois_response
fields	Нет	Список полей для возврата через запятую
excludes	Нет	Список полей, которые нужно исключить, через запятую
force_refresh	Нет	Обойти кэш

get_abuse_contact

Контактные данные для сообщений о злоупотреблениях, связанных с одним IP-адресом, через IP Abuse Contact API. Платный тариф. 1 кредит.

Возвращает маршрут для сообщений о злоупотреблениях, страну, имя контактного лица, организацию, адрес, адреса электронной почты и номера телефонов. Если для того же IP-адреса вам также нужны геолокационные данные или сведения о безопасности, используйте lookup_ip с параметром include=abuse (или include=security,abuse), чтобы получить всё за один вызов.

Параметр	Обязательный	Описание
ip	Нет	IP-адрес
fields	Нет	Список полей для возврата через запятую
excludes	Нет	Список полей, которые нужно исключить, через запятую
force_refresh	Нет	Обойти кэш

get_cached_result

Получает страницу ранее сохранённого результата, который не поместился в один ответ. Доступен на бесплатном и платном тарифах. 0 кредитов. Добавлен в версии 2.0.1.

Параметр	Обязательный	Описание
cursor	Да	Передайте page.cursor из предыдущего ответа, чтобы повторно получить эту страницу, или page.next_cursor, чтобы перейти к следующей

Используйте тот же процесс сервера и тот же ключ API. Чтение страниц продлевает срок хранения снимка при бездействии и никогда не вызывает API, даже в случае ошибки. Описание полей ответа и полный пример восстановления приведены в разделе «Постраничное получение кэшированного результата».

Примеры запросов

Для платного расследования IP-адреса один раз вызовите lookup_ip с параметрами ip: "49.12.212.42", include: "security,abuse" и fields: "location,company,asn,security,abuse". Этот запрос объединяет сведения о местоположении и владельце, индикаторы угроз и контакты для сообщений о нарушениях. Ориентировочная стоимость — 4 кредита. Опишите полученные данные и укажите поля, для которых информации нет; прежде чем рекомендовать разрешить или заблокировать адрес, примените политику пользователя.

Для смешанного набора вызовите bulk_lookup_ip с параметрами ips: ["8.8.8.8", "10.0.0.1", "1.1.1.1"] и fields: "location.country_name". Проверьте structuredContent.errors, чтобы определить частный IP-адрес, а успешные записи используйте напрямую. Два корректных запроса IP-адресов будут стоить ориентировочно 2 кредита; за частный IP-адрес плата не взимается. Большие наборы разбивайте с учётом указанного ограничения на количество входных данных.

ASN идентифицирует сеть, объявляющую маршруты IP-адресов. Anycast позволяет обслуживать один IP-адрес из нескольких мест, поэтому его местоположение не обязательно указывает на сервер, обработавший конкретный запрос. Адрес bogon зарезервирован или по другой причине не маршрутизируется в публичной сети. В сообщении об ошибке upstream означает API IPGeolocation.io, к которому обращается этот сервер.

Местоположение IP-адреса является оценочным. Если доступно, используйте include=geo_accuracy, чтобы оценить степень неопределённости. Оценки угроз и признаки VPN или прокси — это сигналы для расследования, а не гарантии безвредности или злонамеренности трафика. Считайте отсутствующие, равные null или неизвестные индикаторы недоступными данными, а не значением false. Принимайте решение о разрешении или блокировке, учитывая местоположение, владельца, сигналы безопасности и контакты для сообщений о нарушениях, а также собственную политику.

Проверка индикаторов угроз для IP-адреса

• Покажи индикаторы угроз и город для 49.12.212.42, чтобы я мог оценить адрес в соответствии с политикой нашей сети.

• Проверь эти IP-адреса на наличие признаков VPN, прокси, Tor, бота и спама: 49.12.212.42, 2.56.12.11, 8.8.8.8

• Для 49.12.212.42 укажи оценку угроз, относится ли адрес к облачному провайдеру и похож ли он на ретранслятор.

Определение владельца IP-адреса

• Кто использует 1.1.1.1 и какой ASN объявляет его маршрут?

• Для AS24940 перечисли только номера upstream ASN.

• Используется ли для этого IP-адреса anycast и какой префикс маршрута объявляется: 1.1.1.1

Контакты для сообщений о нарушениях

• Для IP-адреса 2.56.12.11 укажи адрес электронной почты, номер телефона и организацию для связи по вопросам нарушений.

• Мне нужны контакт для сообщений о нарушениях по адресу 1.0.0.0 и связанный с ним сетевой маршрут.

• Покажи только контактные данные для сообщений о нарушениях по этому IP-адресу: 1.1.1.1

Запросы и преобразование часовых поясов

• Который сейчас час в Токио?

• Переведи время 2026-03-07 09:30 из часового пояса Нью-Йорка в часовой пояс Токио.

• Какое сейчас местное время в аэропорту JFK?

Данные о восходе, закате и Луне

• Укажи время восхода и заката в Лондоне 2026-06-21.

• Покажи время восхода в Карачи с 2026-03-10 по 2026-03-15.

• Укажи фазу Луны и продолжительность дня в Нью-Йорке 2026-07-17.

Разбор строк user-agent

• Разбери эту строку 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

• Разбери эти строки user-agent одним запросом и укажи браузер, ОС и тип устройства для каждой.

• Похожа ли эта строка user-agent на строку поискового робота или бота? 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)

Примеры ответов и результатов работы инструмента

Примеры ответов ниже приведены для иллюстрации; точная формулировка зависит от модели. Блоки JSON сокращены и не содержат актуальных измерений. Данные о местоположении, владельцах, контактах и текущем времени могут меняться.

Запрос для одного IP-адреса

Запрос: Определи местоположение 91.128.103.196 и укажи страну, город, ASN и местное время.

Пример ответа: IP-адрес 91.128.103.196 находится в Стокгольме, Швеция. ASN — AS1257, оператор — Tele2 Sverige AB. Часовой пояс — Europe/Stockholm; местное время составляло 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"
  }
}

Преобразование времени

Запрос: Переведи время 2025-01-21 13:42:52 из DXB в LHR.

Пример ответа: Время 2025-01-21 13:42:52 в Дубае соответствует времени 2025-01-21 09:42:52 в Лондоне. Разница составляет 4 часа.

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

Контакт для сообщений о нарушениях

Запрос: Укажи контакт для сообщений о нарушениях по адресу 1.0.0.0.

Пример ответа: Контакт для сообщений о нарушениях по адресу 1.0.0.0 — IRT-APNICRANDNET-AU в Австралии; он обслуживает маршрут 1.0.0.0/24. Электронная почта: 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"]
  }
}

Коды ошибок

При сбоях инструмента возвращаются isError: true, понятное текстовое описание и structuredContent.error с сообщением, из которого удалены чувствительные данные и которое ограничено по длине, категорией, возможностью повторного запроса и рекомендациями:

Источник сбоя	Структурированные сведения
От API получен HTTP-ответ с ошибкой	source: "ipgeolocation_api"; status содержит полученный HTTP-статус
Отклонение по зарегистрированной схеме: неверный тип поля, отсутствующее обязательное поле, неизвестный параметр или слишком большой набор данных	source: "mcp_server", category: "validation", retryable: false; запрос отклонён до вызова API
Проверка обработчиком (например, дат или пары координат), отсутствие API-ключа или недоступность результата в кэше	source: "mcp_server", category: "tool_error", retryable: false; HTTP-статус не создаётся
Локальное истечение времени ожидания запроса	source: "mcp_server", category: "timeout", локальный status: 504, retryable: true
Сбой соединения, некорректный JSON или недопустимый ответ провайдера get_my_ip	source: "mcp_server", category: "upstream_request", локальный status: 502, retryable: true
API вернул HTTP-перенаправление	source: "mcp_server", category: "redirect_blocked", локальный status: 502, retryable: false; проверьте перенаправление или обратитесь в службу поддержки

Для проверки входных данных используются зарегистрированные схемы Zod и тот же формат структурированной ошибки, что и при сбоях выполнения. Неизвестные инструменты и некорректные MCP-запросы приводят к ошибкам протокола. Рекомендации по повторной отправке не гарантируют, что повторный запрос будет успешным или бесплатным: локальное истечение времени ожидания может произойти после того, как API обработал платный запрос. HTTP 429 означает достижение лимита кредитов или ограничений подписки, поэтому автоматические повторы сразу после ошибки отключены; повторите запрос, когда кредиты станут доступны.

Следующая таблица относится к HTTP-ошибкам, фактически полученным от API:

Код	Значение
400	Вышестоящий API отклонил параметры запроса или формат входных данных
401	API отклонил ключ, бесплатный тариф вызвал платный инструмент или в бесплатном тарифе указано неанглийское значение lang
404	Ресурс не найден (например, ASN не существует)
405	Ограничение метода или подписки со стороны вышестоящего API
413	Размер тела POST-запроса превышает допустимый для вышестоящего API
415	В POST-запросе отсутствует обязательный тип содержимого application/json
423	Частный, зарезервированный или bogon IP-адрес, включая адреса для документации, например 203.0.113.42 и 198.51.100.27
429	Достигнут дневной лимит кредитов (бесплатный тариф) или превышена квота подписки/доплаты
499	Вышестоящий API сообщает о тайм-ауте запроса клиента или соединения
500, 502, 503, 504, 505	Ошибка на стороне сервера вышестоящего API

Точный код статуса может зависеть от конечной точки и режима запроса. Если вышестоящая конечная точка возвращает статус, не указанный в таблице, сервер не пытается угадать причину. Он передаёт полученные от вышестоящего API статус и сообщение, указывает category: "undocumented_api_error" и рекомендует MCP-клиенту объяснить ответ как неописанный статус вышестоящего API, не придумывая причину.

В пакетных текстовых ответах сохраняется формат API для каждого элемента. Структурированные результаты содержат items в исходном порядке и список errors. Для каждого элемента с ошибкой указываются его индекс input_index, начиная с нуля, исходное значение input, источник, категория, сообщение, возможность повторного запроса и рекомендации. Статус элемента status указывается только в том случае, если его вернул API; для ошибок, содержащих только сообщение, HTTP-статус не создаётся. Если число результатов не совпадает с ожидаемым, возвращается ошибка всего вызова вместо назначения ненадёжных идентификаторов входным данным. Проверяйте каждую запись: успешное выполнение запроса в целом не означает, что обработаны все элементы, а успешные элементы не следует отправлять повторно.

Как это работает

MCP-клиент использует этот сервер для вызова API IPGeolocation.io v3.

Во время работы:

• MCP-клиент запускает процесс сервера.

• Клиент получает список инструментов.

• Если запрос соответствует инструменту, клиент вызывает его.

• Сервер проверяет аргументы и возвращает кэшированный результат или обращается к API. В ответе передаются текстовое содержимое и structuredContent; для всех 17 инструментов указана схема выходных данных.

Результат	structuredContent
Получение одного JSON-объекта	{ "data": ... }
Публичный IP-адрес для исходящих соединений	{ "ip": "..." }
Массовый запрос	{ "items": [...], "errors": [...] }
Слишком большой успешный ответ	{ "page": ... }
Ошибка всего вызова	{ "error": ... } с isError: true

В обычных текстовых ответах сохраняется формат JSON, полученный от API; исключение — get_my_ip, который возвращает строку с IP-адресом. Слишком большие успешные ответы содержат страницу и в текстовом, и в структурированном содержимом.

В аутентифицированных запросах к API ключ передаётся в заголовке x-ipgeolocation-api-key и не добавляется в URL запросов.

Инструкции сервера и описания инструментов помогают MCP-клиенту выбирать инструменты, учитывать стоимость и ограничения, а также интерпретировать результаты. Клиенты сами решают, как передать эти рекомендации своему ассистенту. Возвращаемые данные WHOIS, строки user-agent, имена хостов и сообщения об ошибках считаются недоверенными и не должны переопределять эти инструкции. Если IP-адрес не указан, используется публичный IP-адрес сервера для исходящих соединений; он может отличаться от IP-адреса конечного пользователя. Инструменты безопасности запрашивают сведения об IP-адресах, но не вызывают отдельный API для обнаружения VPN и прокси в браузере в реальном времени.

lookup_company, lookup_currency и lookup_network получают отдельные части полного ответа поиска IP-адреса. Они доступны как самостоятельные инструменты, чтобы MCP-клиенты могли находить их, когда пользователю нужны только отдельные данные.

Кэширование

Сервер хранит кэшированные ответы в памяти процесса и объединяет идентичные запросы с тем же API-ключом, если они уже выполняются. Сеансы с одинаковым ключом используют общее пространство имён кэша; для разных ключей создаются отдельные пространства имён.

Кэшируемые данные	Срок действия по умолчанию	Продлевается ли срок при чтении?
Обычный ответ инструмента	5 минут с момента сохранения	Нет
Полный снимок пагинации	5 минут бездействия	Да, после каждого успешного чтения через get_cached_result

Для обоих типов данных используется IPGEOLOCATION_MCP_CACHE_TTL_MS (по умолчанию 300000 мс). По умолчанию кэш вмещает до 500 записей, включая обычные ответы и снимки страниц. Это ограничение на количество записей, а не на общий объём данных или памяти. Полный снимок может быть значительно больше отдельной страницы.

По истечении срока действия, при удалении из кэша или перезапуске процесса кэшированные данные могут стать недоступны. В таком случае get_cached_result завершится локальной ошибкой и не будет повторно запрашивать данные. Повтор исходного запроса после отсутствия данных в кэше может снова расходовать кредиты.

Параметр force_refresh: true запускает новый запрос к API, даже если уже выполняется идентичный запрос. Результат более старого запроса не сможет перезаписать новый результат в кэше.

Кэшируются: 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

Всегда выполняются в реальном времени (не кэшируются): get_my_ip, get_timezone, convert_timezone, get_astronomy

Переменные окружения

Переменная	Обязательная	Значение по умолчанию	Описание
IPGEOLOCATION_API_KEY	Да (для большинства инструментов)		Ваш API-ключ ipgeolocation.io
IPGEOLOCATION_REQUEST_TIMEOUT_MS	Нет	15000	Тайм-аут запроса к API в мс, включая чтение тела ответа. Диапазон: 1000–120000
IPGEOLOCATION_MCP_CACHE_TTL_MS	Нет	300000	Срок действия обычных ответов и период бездействия снимков страниц в мс. Диапазон: 1000–3600000
IPGEOLOCATION_MCP_CACHE_MAX_ENTRIES	Нет	500	Максимальное количество кэшируемых ответов и снимков страниц; не ограничивает объём памяти в байтах. Диапазон: 10–5000
IPGEOLOCATION_MCP_MAX_BULK_ITEMS	Нет	1000	Максимальное количество элементов во входных массовых запросах; также ограничивается значением IPGEOLOCATION_MCP_MAX_RESULT_ITEMS. Максимум: 50000
IPGEOLOCATION_MCP_MAX_RESULT_ITEMS	Нет	250	Максимальное количество элементов во входных данных и результатах массовых запросов; вложенные массивы возвращаются целиком. Максимум: 50000
IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS	Нет	200000	Максимальный размер полного сериализованного результата инструмента в байтах UTF-8, включая текст и структурированное содержимое. Слишком большие успешные ответы возвращаются страницами из кэша; в слишком больших сообщениях об ошибках текст сокращается. Диапазон: 10000–2000000
IPGEOLOCATION_MCP_MAX_ERROR_CHARS	Нет	4000	Максимальная длина сообщения об ошибке в символах до добавления маркеров усечения. Ограничение на общий размер ответа в байтах может дополнительно сократить сообщение. Диапазон: 200–50000

Массовые запросы, размер которых превышает действующий лимит элементов, отклоняются до обращения к API и не расходуют кредиты. Если увеличить только IPGEOLOCATION_MCP_MAX_BULK_ITEMS, действующий лимит не изменится. Для обработки более крупных пакетов увеличьте оба параметра, ограничивающие число элементов.

Ограничение на размер ответа учитывает текстовое и структурированное содержимое, экранирование JSON и кодирование UTF-8. При необходимости успешные результаты сохраняют все записи и вложенные массивы и возвращаются страницами из кэша. В слишком больших сообщениях об ошибках сокращается только текст: категория ошибки, возможность повторного запроса, рекомендации и код статуса сохраняются.

Пагинация кэшированных результатов

Вызов get_cached_result стоит 0 кредитов и никогда не обращается к API, даже если курсор неверен, истёк, удалён из кэша или стал недоступен после перезапуска сервера. Для вызова нужен один обязательный параметр cursor, который возвращается в page.cursor или page.next_cursor. Используйте тот же процесс сервера и тот же API-ключ.

Если исходный запрос возвращает слишком большой результат, вместо обычного data или items/errors он вернёт { "page": ... }. Каждая страница содержит:

Поле	Значение
source_tool	Инструмент, выполнивший исходный запрос
format	structuredContent_json
json_fragment	Часть полного структурированного JSON-результата исходного запроса
offset, total_chars	Позиция фрагмента и длина всего JSON в кодовых единицах UTF-16
cursor	Позволяет повторно получить эту страницу без повторения исходного запроса
next_cursor	Позволяет получить следующую страницу; отсутствует на последней странице
expires_at	Время истечения срока действия после бездействия; успешные чтения продлевают срок, по умолчанию — на пять минут

Передавайте каждый next_cursor в get_cached_result, объединяйте строки json_fragment в порядке смещения и разбирайте полученную строку JSON один раз. Отдельный фрагмент не обязательно является корректным JSON. Это позволяет обрабатывать даже одну запись или строку, превышающую размер страницы. При массовых запросах в результате восстанавливается полный объект { "items": [...], "errors": [...] } с сохранением входных идентификаторов и статусов. Для одиночных запросов восстанавливается { "data": ... }.

let response = await client.callTool({ name: "bulk_lookup_ip", arguments: { ips } });
if (response.isError) throw new Error(response.content[0].text);
let complete = response.structuredContent;
if (complete.page) {
  let json = "";
  for (;;) {
    const page = response.structuredContent.page;
    json += page.json_fragment;
    if (!page.next_cursor) break;
    response = await client.callTool({
      name: "get_cached_result", arguments: { cursor: page.next_cursor }
    });
    if (response.isError) throw new Error(response.content[0].text);
  }
  complete = JSON.parse(json);
}

Используйте курсоры, чтобы получить оставшиеся данные. Правила кэширования описывают срок действия снимков, их удаление из кэша, изоляцию по API-ключам и случаи, когда новый запрос может расходовать кредиты.

Сборка из исходного кода

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

Запустите сервер напрямую:

node dist/cli.js

Перед запуском команды задайте IPGEOLOCATION_API_KEY в настройках закрытого окружения вашей оболочки. Процесс ожидает MCP-сообщения в stdin и не отображает интерактивную командную строку.

Проверьте сервер с помощью MCP Inspector:

npx @modelcontextprotocol/inspector node dist/cli.js

Docker

docker build -t ipgeolocation-mcp .
docker run --rm -i -e IPGEOLOCATION_API_KEY ipgeolocation-mcp

Сначала задайте IPGEOLOCATION_API_KEY в закрытом окружении вашей оболочки. Образ содержит Node.js и запускается от имени непривилегированного пользователя node. Флаг -i в Docker оставляет stdin открытым для MCP-сообщений. Не указывайте -t, чтобы протокол использовал обычные stdin и stdout.

Итоговый образ напрямую запускает собранный сервер. На этапе сборки доступны npm и Yarn; образ для запуска содержит Node.js и установленные производственные зависимости.

После сборки образа настройте MCP-клиент, использующий локальные команды:

{
  "mcpServers": {
    "ipgeolocation": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "IPGEOLOCATION_API_KEY", "ipgeolocation-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Тестирование

Примеры настройки клиентов описывают форматы конфигурации. Проверки установки через графический интерфейс и в разных операционных системах проводите отдельно от тестов протокола, пакета и Docker; см. контрольный список выпуска.

npm test               # полный набор тестов
npm run test:unit      # только модульные тесты
npm run test:integration  # только интеграционные тесты

Проверочные тесты с реальными данными используют настоящий MCP-клиент stdio и расходуют кредиты API. Переменная IPGEOLOCATION_FREE_KEY вместе с командой npm run test:live:free проверяет семь основных инструментов, ограничения платных функций, резервные сценарии для данных о владельце и сети, а также фактически доступный пакетный режим. Тест сообщает, если доступ к пакетному режиму отличается от документированной политики, согласно которой эта функция доступна только в платных планах. Переменная IPGEOLOCATION_PAID_KEY вместе с командой npm run test:live:paid проверяет все 16 инструментов API, платные модули, структурированные ошибки валидации, пакетные запросы со смешанными корректными и приватными адресами, а также локальное чтение кэшированных результатов. Проверка платного ключа не подтверждает ограничения бесплатного плана.

После сборки проверьте полную пагинацию кэшированных результатов с помощью любого из ключей:

node tests/pagination.stdio.mjs free  # использует IPGEOLOCATION_FREE_KEY
node tests/pagination.stdio.mjs paid  # использует IPGEOLOCATION_PAID_KEY

Каждый запуск выполняет один запрос к API с шестью IP-адресами и проверяет, что указано списание шести кредитов. Тест сравнивает полученные записи с хешем полного ответа API и проверяет, что чтение страниц, повторное воспроизведение результатов, истечение срока действия и перезапуск процесса не приводят к дополнительным запросам API. На время теста уменьшаются лимит размера ответа дочернего сервера и время хранения кэша; конфигурация вашего сервера не меняется.

Чтобы проверить то же поведение в собранном выше образе:

node tests/pagination.stdio.mjs free docker run --rm -i \
  -e IPGEOLOCATION_API_KEY -e IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS \
  -e IPGEOLOCATION_MCP_CACHE_TTL_MS -e NODE_OPTIONS ipgeolocation-mcp

Устранение неполадок

Клиент использует старую версию инструмента после обновления: Перезапустите процесс сервера и проверьте его версию в сведениях о подключении MCP в клиенте. Сравните её с последней версией в npm. Перед перезапуском пересоберите установки из исходного кода и Docker.

Не настроен ключ API: Укажите IPGEOLOCATION_API_KEY в конфигурации сервера клиента. Эта локальная ошибка не содержит HTTP-статуса и не приводит к запросу к внешнему сервису.

Ошибки 401: API отклонил ключ или запрошенную функцию. Проверьте, активен ли ключ и поддерживает ли ваш план нужный инструмент. Для поиска доменов с помощью lookup_ip также требуется платный план.

Ошибки 423: Используйте общедоступный маршрутизируемый IP-адрес. Частные или зарезервированные адреса, например 10.0.0.1 и 203.0.113.42, предназначенный для документации, не подходят для успешных примеров геолокации.

Локальные тайм-ауты 504: При значении source: "mcp_server" запрос или чтение тела ответа превысили установленный срок. Проверьте подключение или увеличьте значение IPGEOLOCATION_REQUEST_TIMEOUT_MS (по умолчанию — 15000 мс, максимум — 120000 мс). При значении source: "ipgeolocation_api" статус 504 получен в HTTP-ответе от API.

Перенаправление заблокировано: Сервер получил неожиданный HTTP-ответ с перенаправлением и остановил обработку до передачи учётных данных или данных запроса. Не повторяйте запрос автоматически. Проверьте конечную точку API или обратитесь в службу поддержки, приложив очищенное от конфиденциальных данных сообщение об ошибке.

Кэшированный результат недоступен: Курсор связан с другим ключом или процессом либо снимок данных устарел или был удалён из кэша. Неудачное чтение страницы не вызвало запрос к API. Новый поиск может расходовать кредиты.

Клиент запрашивает URL для MCP: Этот пакет предоставляет локальную команду stdio. Используйте клиент или хост, способный запустить её; для подключения только к удалённым сервисам требуется размещённая конечная точка MCP.

Цены

Сведения о действующих планах, кредитах и ценах см. на странице тарифов IPGeolocation.

Ссылки

• Сайт IPGeolocation

• Документация API IPGeolocation

• Тарифы IPGeolocation

• Получить бесплатный ключ API IPGeolocation

• История изменений

• Политика безопасности

• Участие в разработке

• Контрольный список выпуска

Лицензия

MIT

Политика конфиденциальности

При поиске через API запрошенные данные передаются в IPGeolocation.io. Сервис также получает публичный IP-адрес, с которого сервер выходит в интернет. Сервер хранит результаты в кэше в памяти процесса. Конфигурация и хранение журналов MCP-клиента или хостинг-провайдера находятся под их контролем. Сведения о сроках хранения см. в Политике безопасности, а информацию об обработке данных провайдером — в Политике конфиденциальности IPGeolocation.