IPGeolocation.io MCP Server

IPGeolocation.io MCP 服务

官方 IPGeolocation.io MCP 服务提供 17 种工具，用于精准的 IP 地理定位、公司信息、ASN 和网络数据、IP 安全检测（VPN、代理、Tor、机器人、托管和垃圾信息检测）、滥用行为联系人、时区、天文学、货币数据以及用户代理解析。

MCP（Model Context Protocol）将客户端连接到这些工具。您的客户端或宿主必须支持通过 stdio 启动本地命令。配置示例请参阅按客户端安装。

本 README 介绍的是 2.0.2。 下方的 npx 命令和 Cursor 安装链接遵循 npm 的 latest 标签，包括未来的主版本。重启服务以加载更新；如果所选版本没有变化，npm 会重复使用缓存的包文件。版本发布详情请参阅更新日志。

项目	值
软件包	ipgeolocation-io-mcp
版本	2.0.2
发布日期	2026-10-27
传输方式	stdio
Node.js	>=22

快速开始

1. 创建免费的 IPGeolocation API 密钥。
2. 将此条目合并到客户端的私有配置中，并保留已有的服务。配置位置请参阅按客户端安装。Cursor 还提供一键安装程序。

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

3. 重新加载服务或重启客户端。
4. 提问 “8.8.8.8 位于哪里？”

目录

• 快速开始
• 按客户端安装
• 验证是否正常工作
• 按套餐划分的工具
• 工具参考
• 提示词示例
• 示例回答和工具输出
• 错误代码
• 工作原理
• 缓存
• 缓存结果分页
• 环境变量
• 从源代码构建
• Docker
• 测试
• 故障排除
• 定价
• 链接
• 许可证
• 隐私政策

按客户端安装

要求

• npm/源码安装需要 Node.js 22 或更高版本，或使用兼容的 Node.js 运行时托管的捆绑包
• npm 配置示例需要 npx 可用
• 大多数 API 工具需要 IPGeolocation.io API 密钥

请使用受支持的 Node.js 版本，并安装最新的安全更新。

get_my_ip 无需 API 密钥。其余 15 个 API 工具都需要 API 密钥。get_cached_result 会读取已保存在内存中的结果；请使用原始查询所用的同一个 API 密钥。

注册免费 IPGeolocation API 密钥

请将真实密钥保存在私有用户配置中，或使用客户端的密钥/环境变量设置。不要将密钥提交到项目配置中。除非格式有所不同，否则以下每个客户端都使用快速入门服务条目。

Codex CLI

运行以下命令前，请在私有 Shell 环境中设置 IPGEOLOCATION_API_KEY。通过引用变量，可以避免在输入的命令及其 Shell 历史记录中留下密钥值。

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 密钥。请参阅 Anthropic 的桌面扩展指南。该目录分发的是已批准的发布版捆绑包；其更新可能晚于 GitHub Releases。请检查已安装的版本，或下载下方的指定版本捆绑包。

如需手动配置 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 的客户端，请从 GitHub Releases 下载已发布的 v2.0.2 .mcpb 捆绑包。该捆绑包包含服务及其依赖项；其宿主仍需 Node.js 22+ 运行时。宿主提示配置捆绑包时，请输入 API 密钥。

Cline

在 Cline 中，打开 MCP Servers > Configure > Configure MCP Servers。在设置 JSON 的 mcpServers 下添加快速入门条目。默认情况下，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 插件

此仓库包含一个适用于 ipgeolocation-io-mcp 的 Cursor 插件。该插件在本地通过 stdio 运行，并且需要 Node.js 22 或更高版本。

要在本地安装，请将此仓库克隆到 ~/.cursor/plugins/local/ 下的新目录中，重新加载 Cursor，然后打开 Customize > Plugins。

• **本地插件：**在启动 Cursor 的环境中设置 IPGEOLOCATION_API_KEY。插件会从该环境中读取密钥。
• **从 Marketplace 安装：**在插件的私有配置中设置密钥。

如果 API 密钥为空或未设置，get_my_ip 仍可正常使用。需要密钥的 API 工具会返回缺少密钥错误，且不会发送请求。

要在 Cursor CLI 中加载本地检出版本：

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

需要密钥的 API 请求会使用你账户的套餐和额度。get_cached_result 工具会读取已保存的响应页面，不会再次发起 API 请求。

请只使用一种方法安装此服务，因为使用多种方法会导致工具条目重复。你可以保留现有配置中的其他服务。

Windsurf / Cascade

在 Cascade 的 ... (Actions) 菜单中，在 MCP 部分选择 Open MCP config file。将快速入门条目合并到你所安装版本打开的文件中；配置路径会因版本而异。对于较新版本中的活动 Agent 和配置位置，请参阅供应商的 Cascade MCP 指南。

保存文件，然后在客户端中重新加载该服务。

Kiro Powers

Kiro Power 提供 17 个工具，涵盖 IP 地理定位、公司信息、ASN 和网络数据、IP 安全（VPN、代理、Tor、机器人、托管和垃圾信息检测）、滥用联系信息、时区、天文学、货币数据和用户代理解析。它在本地通过 stdio 运行 ipgeolocation-io-mcp，遵循 npm 的 latest 标签，并且需要 Node.js 22 或更高版本。通过 Powers > Add Custom Power 导入 packaging/kiro 文件夹，并按照设置指南配置你的私有 API 密钥。大多数工具都需要密钥；访问权限和额度取决于你的套餐。

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。除非你想更改缓存、超时或输出限制，否则请将其他环境变量字段留空。

如果你还没有密钥，可以创建免费的 IPGeolocation API 密钥。

其他 MCP 客户端

在客户端的配置格式中使用快速入门中的 ipgeolocation 服务条目。客户端必须支持启动本地 stdio 进程。仅接受远程 MCP URL 的客户端需要托管端点；此软件包提供服务命令。

验证是否正常工作

设置完成后，请尝试以下操作：

提示词	预期工具
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
提供 Karachi 在 2026-03-10 至 2026-03-15 的日出时间。	get_astronomy_time_series
解析此用户代理：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.2 版提供 16 个 API 工具，以及一个零积分的页面读取工具 get_cached_result。批量工具默认接受 250 个输入；实际上限取两个项目数限制设置中较低者。

所列费用适用于成功的上游请求。缓存命中和读取缓存页面不会额外消耗积分。实际计费以 API 的 X-Credits-Charged 响应标头为准；请参阅积分规则。

免费套餐

每天 1,000 积分。以下 7 个 API 工具提供其文档中所述的核心数据；get_cached_result 还可读取先前返回的页面，费用为 0 积分：

工具	积分	功能
lookup_ip	1	查询一个 IP 的位置、时区、货币和 ASN
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 文档说明批量地理定位仅限付费套餐；使用免费套餐密钥进行的实时检查也返回了基本批量结果。套餐权限由上游决定，因此不应仅凭这一观察认定免费套餐支持批量查询。

付费套餐

提供全部 17 个工具，包括零积分的缓存结果读取工具。付费套餐还会为 lookup_ip 增加 network、company 和扩展的 asn 字段，并提供 include 参数，可选值为 security、abuse、hostname、liveHostname、hostnameFallbackLive、user_agent、geo_accuracy、dma_code 或 *。

工具	积分	功能
bulk_lookup_ip	每个 IP 1 积分	批量地理定位，默认接受 250 个输入
check_security	2	检查 VPN、代理、Tor、机器人、垃圾信息和威胁标记
bulk_security_check	每个 IP 2 积分	批量威胁检查
lookup_company	1	查询一个 IP 的公司名称和 ASN 持有者
lookup_network	1	查询路由前缀、连接类型和任播状态
parse_user_agent	1	将一个 UA 字符串解析为浏览器、设备、操作系统和引擎信息
bulk_parse_user_agent	每个 UA 1 积分	批量解析 UA，默认接受 250 个字符串
lookup_asn	1	查询 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 Geolocation API 查询单个 IP 或域名。免费和付费均可使用。基础 IP 数据消耗 1 个额度。

当你需要查询单个 IP 地址的位置、时区、货币或 ASN 时，请使用此工具。付费套餐可通过添加 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 中。显式包含的模块即使被 fields 忽略，也仍会保留。你可以排除嵌套字段，但由 fields 指定的根字段或显式包含的模块仍会保留。include=* 会遵循字段选择和排除设置，但不会保护这些根字段。缓存结果遵循与新响应相同的规则。

bulk_lookup_ip

批量查询 IP。付费。每个 IP 消耗 1 个额度。

接受包含 IP 或域名的数组（默认最多 250 个）。批次限制取 IPGEOLOCATION_MCP_MAX_BULK_ITEMS 和 IPGEOLOCATION_MCP_MAX_RESULT_ITEMS 中的较小值。支持与 lookup_ip 相同的 include、fields 和 excludes 选项。

参数	必填	描述
ips	是	IP 地址或域名数组
lang	否	响应语言
include	否	每个 IP 的额外模块
fields	否	以逗号分隔的每个 IP 要返回的字段
excludes	否	以逗号分隔的每个 IP 要排除的字段
force_refresh	否	跳过缓存

get_my_ip

返回运行服务的机器的公网 IP。免费。0 个额度。无需 API 密钥。

不接受任何参数。始终访问网络（不使用缓存）。可用于快速确认服务进程是否正常运行。

check_security

通过 IP Security API 获取某个 IP 的威胁与匿名性数据。付费。2 个额度。

返回威胁评分、VPN/代理/Tor 标记、提供商名称、置信度评分、机器人/垃圾信息指示、匿名性标记以及云服务提供商状态。

如果同一条提示词还需要位置或 ASN，请使用 lookup_ip 并设置 include=security，即可在一次请求中获取这些信息。费用为 3 个额度，与单独进行安全检查和基础查询的费用相同。如果还需要滥用联系信息，请将 abuse 添加到 include。

参数	必填	描述
ip	否	要检查的 IP 地址
fields	否	以逗号分隔的要返回的字段
excludes	否	以逗号分隔的要排除的字段
force_refresh	否	跳过缓存

bulk_security_check

check_security 的批量版本。**付费。每个 IP 2 个额度。**默认最多接受 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 可能与您的 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

通过 User-Agent API 将一个 UA 字符串解析为浏览器、设备、操作系统和引擎数据。付费。1 个积分。

还会对机器人和爬虫进行分类。注意：此工具会解析你传入的 uaString。它不会从 MCP 连接本身推断调用方的 UA。

参数	必填	说明
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

查询一个 IP 的公司详情和 ASN 归属。公司详情需要付费；免费套餐仅返回基本 ASN 信息。1 个积分。

返回 company 和 asn 对象。lookup_ip 会返回相同数据，以及位置、时区等更多信息。如果你只需要公司/ASN 信息，并希望获得更小的响应，请使用此工具。

参数	必填	说明
ip	否	IP 地址
force_refresh	否	跳过缓存

lookup_currency

查询一个 IP 对应的货币、国家/地区电话区号、顶级域名和语言。免费和付费。1 个积分。

返回 currency 和 country_metadata 对象。

参数	必填	说明
ip	否	IP 地址
force_refresh	否	跳过缓存

lookup_network

单个 IP 的路由前缀、连接类型和任播状态。付费。1 个积分。

返回包含 connection_type、route 和 is_anycast 的 network 对象。如果 API 未提供网络数据，此工具会返回本地错误，而不是空成功响应。这不会伪造上游 HTTP 状态，而且 API 调用可能已经消耗了积分。

参数	必填	描述
ip	否	IP 地址
force_refresh	否	跳过缓存

lookup_asn

通过 ASN API 获取网络分配和关系数据。付费。1 个积分。

使用此工具获取 ASN 详情，以及可选的对等方、上游、下游、路由和 WHOIS 数据集。通过 include 请求所需的数据集，然后筛选缓存结果以获取不同的数据切片。lookup_ip 也会在 IP 查询中提供 ASN 元数据。

fields 会自动启用其引用的可选数据集，例如 upstreams.as_number。单独使用 excludes 不会请求额外的数据集。

参数	必填	描述
asn	否	ASN（例如 AS13335 或 13335）
ip	否	要解析为 ASN 的 IP 地址
include	否	peers、downstreams、upstreams、routes、whois_response
fields	否	要返回的逗号分隔字段
excludes	否	要排除的逗号分隔字段
force_refresh	否	跳过缓存

get_abuse_contact

通过 IP Abuse Contact API 获取单个 IP 的滥用联系信息。付费。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 调查，使用 ip: "49.12.212.42"、include: "security,abuse" 和 fields: "location,company,asn,security,abuse" 调用一次 lookup_ip。这样可以整合位置、所有权、威胁指标和滥用联系信息，预计消耗 4 个积分。说明证据和任何未知字段；在建议允许或阻止之前，先应用用户的策略。

对于混合批次，使用 ips: ["8.8.8.8", "10.0.0.1", "1.1.1.1"] 和 fields: "location.country_name" 调用 bulk_lookup_ip。检查 structuredContent.errors，找出私有 IP 输入，并直接使用成功记录。两次有效 IP 查询预计消耗 2 个积分；私有 IP 不计费。较大的批次应按公布的输入上限拆分。

ASN 标识一个通告 IP 路由的网络。Anycast 允许在多个位置提供同一个 IP，因此其位置未必能标识处理特定请求的服务器。bogon 地址是保留地址，或以其他方式无法在公网路由的地址。错误中的 Upstream 指此服务联系的 IPGeolocation.io API。

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，仅列出上游 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 的月相和白昼时长。

解析用户代理字符串

• 解析此用户代理：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
• 批量解析这些用户代理，并告诉我每个用户代理对应的浏览器、操作系统和设备类型。
• 此用户代理看起来像爬虫或机器人吗？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 和当地时间。

示例回答： 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。电子邮件：[email protected]。

{
  "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": ["[email protected]"]
  }
}

错误代码

工具失败时会返回 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 表示额度或订阅限制，因此会禁用立即自动重试；请在额度可用后重试。

下表适用于实际从 API 收到的 HTTP 错误：

代码	含义
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 服务器端错误

确切的状态码可能因端点和请求模式而异。如果上游端点返回的状态码不在此表中，服务不会猜测原因。它会传递上游状态码和消息，并附上 category: "undocumented_api_error"，同时指导 MCP 客户端将响应说明为未记录的上游状态，不要虚构原因。

批量文本会保留 API 的逐项格式。结构化结果包含按输入顺序排列的 items，以及一个 errors 列表。每个失败项都包含从零开始的 input_index、原始 input、来源、类别、消息、是否可重试以及指导信息。仅当 API 提供了条目的 status 时才会包含该字段；只有消息的错误不会被赋予虚构的 HTTP 状态码。如果结果数量不匹配，则返回整个调用的错误，而不会分配不可靠的输入标识符。请检查每条记录；请求整体成功并不能说明每一项都成功，也不应重试成功的条目。

工作原理

MCP 客户端通过此服务调用 IPGeolocation.io v3 API。

运行时：

1. MCP 客户端启动服务进程。
2. 客户端读取工具列表。
3. 当提示词与某个工具匹配时，客户端调用该工具。
4. 服务验证参数，并返回缓存结果或调用 API。它会返回文本内容以及 structuredContent；全部 17 个工具都声明了输出架构。

结果	structuredContent
单条 JSON 查询	{ "data": ... }
公网出口 IP	{ "ip": "..." }
批量查询	{ "items": [...], "errors": [...] }
超大成功响应	{ "page": ... }
整个调用失败	{ "error": ... }，并带有 isError: true

普通文本响应保留 API 的 JSON 格式；get_my_ip 则返回纯 IP 字符串。超大的成功响应会在文本和结构化内容中都包含一个页面。

经过身份验证的上游请求会在 x-ipgeolocation-api-key 标头中发送 API 密钥。密钥不会添加到请求 URL 中。

服务说明和工具描述会向 MCP 客户端说明工具选择、费用、限制和结果解读。客户端自行决定如何向助手呈现这些指导。返回的 WHOIS 文本、用户代理、主机名和错误消息均为不可信数据，不得覆盖这些说明。省略 IP 选择器时，指的是服务所在机器的公网出口 IP，该 IP 可能与最终用户的 IP 不同。安全工具查询 IP 情报；它们不会调用单独的、基于浏览器的实时 VPN／代理检测 API。

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 会启动新的上游请求，即使相同请求正在运行也不例外。较早的请求无法覆盖其缓存结果。

已缓存： 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	是（大多数工具需要）		你的 ipgeolocation.io API 密钥
IPGEOLOCATION_REQUEST_TIMEOUT_MS	否	15000	上游截止时间，单位为毫秒，包括读取响应正文。范围：1000-120000
IPGEOLOCATION_MCP_CACHE_TTL_MS	否	300000	正常响应的 TTL 和页面快照空闲 TTL，单位为毫秒。范围：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 不消耗额度，且绝不会调用 API，即使游标无效、已过期、已被逐出，或在服务器重启后不可用也是如此。它接受一个必填的 cursor，该游标由 page.cursor 或 page.next_cursor 返回。请使用同一服务器进程和 API 密钥。

大型原始查询会返回 { "page": ... }，而不是常规的 data 或 items/errors。每个页面包含：

字段	含义
source_tool	原始查询工具
format	structuredContent_json
json_fragment	完整原始结构化 JSON 结果的一部分
offset, total_chars	片段位置和完整 JSON 长度，单位为 UTF-16 代码单元
cursor	重放此页面，无需重复查询
next_cursor	读取下一页；最后一页中不存在
expires_at	空闲过期时间戳；成功读取会延长 TTL，默认值为五分钟

使用 get_cached_result 读取每个 next_cursor，按偏移量顺序拼接 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

运行命令前，请通过 shell 的私有环境设置配置 IPGEOLOCATION_API_KEY。进程会等待从 stdin 接收 MCP 消息；它不会显示交互式提示。

使用 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

请先在私有 shell 环境中设置 IPGEOLOCATION_API_KEY。镜像包含 Node.js，并以非特权用户 node 运行。Docker 的 -i 标志会保持标准输入打开，以接收 MCP 消息。省略 -t，让协议使用普通的标准输入/标准输出。

镜像基于官方 Node.js 24.22.1 Alpine 3.24 基础镜像，使用 musl，并直接运行编译后的服务。该服务没有原生 Node.js 插件。构建阶段提供 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>"
      }
    }
  }
}

测试

客户端设置示例介绍了配置格式。请将 GUI 和操作系统安装检查与协议、软件包及 Docker 测试分开记录；请参阅发布清单。

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

在线冒烟测试使用真实的 stdio MCP 客户端，并会消耗 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  # uses IPGEOLOCATION_FREE_KEY
node tests/pagination.stdio.mjs paid  # uses IPGEOLOCATION_PAID_KEY

每次运行都会发起一次包含 6 个 IP 的 API 请求，并检查报告的 6 个额度。它会将恢复的记录与完整上游响应的哈希值进行比较，并验证分页读取、重放、过期和进程重启均不会产生额外 API 调用。测试会临时降低子服务的响应预算和缓存 TTL；你的服务配置不会改变。

若要在上文构建的镜像中检查相同行为：

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 ms，最大值：120000 ms）。当 source: "ipgeolocation_api" 时，504 是 API 返回的 HTTP 响应。

**重定向被阻止：**服务收到了意外的 HTTP 重定向，并在转发凭据或请求数据前停止。请勿自动重试。请调查 API 端点，或联系支持人员并提供已脱敏的错误信息。

**缓存结果不可用：**游标属于其他密钥或进程，或者快照已过期或被逐出。失败的分页读取没有发起 API 调用。新的查询可能会消耗额度。

**客户端要求提供 MCP URL：**此软件包提供本地 stdio 命令。请使用能够启动该命令的客户端或宿主；仅支持远程连接的连接器需要托管的 MCP 端点。

定价

有关当前套餐详情、额度和定价，请参阅 IPGeolocation 定价页面。

链接

• IPGeolocation 网站
• IPGeolocation API 文档
• IPGeolocation 定价
• 创建免费的 IPGeolocation API 密钥
• 更新日志
• 安全策略
• 贡献指南
• 发布清单

许可证

MIT

隐私政策

API 查询会将请求的输入发送至 IPGeolocation.io，该服务也会收到服务器机器的公网出口 IP。服务器会在进程内存中缓存结果。你的 MCP 客户端或托管服务提供商负责管理自身的配置和日志存储。有关数据保留详情，请参阅安全策略；有关服务提供商的数据处理方式，请参阅 IPGeolocation 隐私政策。