Ipgeolocation Io MCP

IP地理定位.io MCP服务器


](https://www.npmjs.com/package/ipgeolocation-io-mcp) ](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases)   ](https://nodejs.org/) 

官方MCP服务器 IP地理定位.io。包括16个MCP工具：IP地理定位、威胁/VPN/代理检测、时区查找和转换、日出/日落/月亮数据、ASN详细信息、滥用联系人和用户代理解析。七种工具适用于免费计划（1000学分/天）。付费计划解锁所有16个以上的批量端点（每次通话最多1000个项目）。

适用于Claude Desktop、Cursor、Windsurf、VS Code、Codex、Cline、Glama和任何其他MCP客户端。

快速开始

1. 创建一个免费的IPGeolocation API密钥

1. Cursor用户可以一键安装：


1. 将此添加到MCP客户端配置中（请参阅 客户端安装 下面是您的客户端的确切配置文件路径）：

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

1. 重新启动客户端。

1. 测试：问 “8.8.8.8位于何处？”

目录

• 快速开始
• 客户端安装
• 验证它是否有效
• 按计划列出的工具
• 工具参考
• 提示示例
• 示例答案和工具输出
• 错误代码
• 运作原理
• 缓存
• 环境变量
• 从源头构建
• 码头工人
• 测试
• 故障排除
• 定价
• 链接
• 许可证
• 隐私政策

客户端安装

需求

• Node.js 18或更高版本
• npx 在您的终端中可用
• 大多数工具的IPGeolocation.io API密钥

get_my_ip 在没有API密钥的情况下工作。其他一切都需要一个。

注册免费的IPGeolocation API密钥

Codex CLI

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

添加服务器后启动新的Codex会话。

克劳德桌面版

增添 claude_desktop_config.json:

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

保存后重新启动Claude Desktop。我们也发货 manifest.json 适用于支持MCP Bundles的客户。

克莱恩

打开MCP服务器面板> 配置 > 高级MCP设置.添加到 cline_mcp_settings.json:

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

保存后重新启动Cline。

光标

一键安装：


或添加到 .cursor/mcp.json 手动：

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

保存后重新启动Cursor。

帆板运动

增添 ~/.codeium/windsurf/mcp_config.json:

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

保存后重新启动Windsurf。

VS代码/GitHub副本

添加到您的VS代码 settings.json:

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

保存后重新启动VS Code。

格拉玛

您可以在上尝试服务器 格拉玛 直接。仅 IPGEOLOCATION_API_KEY 是必需的。除非您想更改缓存、超时或输出限制，否则请将其他环境变量字段留空。

如果你还没有钥匙， 创建一个免费的IPGeolocation API密钥.

任何其他MCP客户端

使用此配置：

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

验证它是否有效

安装后尝试以下操作：

按计划列出的工具

免费计划

每天1000学分。这7个工具可用：

付费计划

全部16个工具。付费计划还增加 network, company，并扩展 asn 字段到 lookup_ip，加上 include 参数 security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code，或 *.

学分数学 lookup_ip 随着 include:

有关当前计划的详细信息和定价，请参阅 IP地理定位定价页面.

工具参考

lookup_ip

单IP或域查找。 免费和付费。1学分。

当您需要一个IP地址的位置、时区、货币或ASN时，请使用此选项。在付费计划中，您可以添加 include 模块在同一调用中提取安全、滥用或主机名数据，从而避免了额外的请求。

免费计划返回基本位置、国家元数据、货币、时区和基本ASN。付费计划添加 network, company，扩展ASN，以及 include 参数。请注意，域查找需要付费计划。

提示：组合 include 随着 fields 可以降低你的信贷成本。例如， include=security&fields=security 花费2个学分而不是3个学分，因为你跳过了基础地理定位响应。同样地， include=abuse&fields=abuse 花费1个学分，而不是2个学分。

bulk_lokup_ip

批量IP查找。 支付。每IP 1学分。

接受一组IP或域（默认情况下最多1000个，可配置为 IPGEOLOCATION_MCP_MAX_BULK_ITEMS).支持相同 include, fields，以及 excludes 选项如 lookup_ip.

get_my_ip

返回运行服务器的计算机的公共IP。 免费。0学分。不需要API密钥。

不接受任何参数。始终访问网络（不缓存）。作为确认服务器进程已启动的快速检查非常有用。

check_security

一个IP的威胁和匿名数据。 支付。2学分。

返回威胁评分、VPN/代理/Tor标志、提供商名称、置信度评分、机器人/垃圾邮件指标、匿名标志和云提供商状态。

如果同一提示还要求提供位置、ASN或滥用数据，您最好使用 lookup_ip 随着 include=security 因为它将所有内容捆绑在一个通话中（总共3个学分，而不是单独的2+1）。

批量安全检查

批量版本 check_security. 支付。每个IP 2个学分。

get_timezone

位置的当前时间和时区详细信息。 免费和付费。1学分。

接受IANA时区名称、坐标、IP地址、机场代码（IATA/ICAO）或UN/LOCODE。该响应包括时区偏移、日期/日期时间变量、时间序列、时间序列号、时间序列码、时间序列序列号、日期序列号、位置序列号、速度序列号、距离序列号、方向序列号、方位序列号、经度序列号、纬度序列号、高度序列， current_time, current_time_unix, time_24, time_12, week, month, year、时区缩写和夏令时转换详细信息。

始终访问网络（未缓存），因为它返回当前时间。

convert_timezone

转换两个位置之间的时间。 免费和付费。1学分。

采用与相同的位置输入类型 get_timezone 无论是源还是目标。如果你遗漏了 time 参数，它转换当前时间。始终访问网络（不缓存）。

天文学

同一日期同一地点的太阳和月亮数据。 免费和付费。1学分。

返回日出、日落、月出、月落、晨昏和黄昏、太阳正午、日长、月相、太阳/月亮状态标志和实时太阳/月亮位置（高度、方位角）。

始终访问网络（未缓存），因为跳过 date 默认为今天。

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 在一定范围内重复。

parse_user_agent

将一个UA字符串解析为浏览器、设备、操作系统和引擎数据。 支付。1学分。

还对机器人和爬虫进行了分类。注意：这将解析 uaString 您传入。它不会从MCP连接本身推断出呼叫者UA。

退货 name, type, version, device, engine，以及 operating_system.

bulk_parse_user_agent

批量版本 parse_user_agent. 支付。每串1学分。

默认情况下，每个请求最多占用1000个字符串（可配置为 IPGEOLOCATION_MCP_MAX_BULK_ITEMS).

lookup_公司

只返回一个IP的公司名称和ASN持有者。 支付。1学分。

退货 company 和 asn 物体。 lookup_ip 返回相同的数据以及位置、时区等。当公司/ASN对是您所需要的，并且您希望得到较小的响应时，请使用此选项。

lookup_货币

一个IP的货币、国家呼叫代码、TLD和语言。 免费和付费。1学分。

退货 currency 和 country_metadata 物体。

lookup_网络

一个IP的路由前缀、连接类型和任意播状态。 支付。1学分。

返回一个 network 对象与 connection_type, route，以及 is_anycast.

lookup_asn

完整的ASN查找。 支付。1学分。

lookup_ip 也返回一个 asn 对象，但仅包含基本元数据。此工具返回完整的ASN记录，包括对等体、上游、下游、路由和WHOIS。用 include 您需要的字段，然后在本地进行筛选，而不是对不同的切片进行多次调用。

get_abuse_contact

滥用一个IP的联系方式。 支付。1学分。

返回滥用途径、国家、联系人姓名、组织、地址、电子邮件地址和电话号码。如果您还需要同一IP的地理位置或安全数据，请使用 lookup_ip 随着 include=abuse （或 include=security,abuse)在一个电话里得到一切。

提示示例

检查IP是否安全

• 49.12.212.42信任我们的网络安全吗？给我威胁摘要和城市。
• 检查这些IP的VPN、代理、Tor、bot和垃圾邮件指示器：49.12.212.42、2.56.12.11、8.8.8.8
• 对于203.0.113.42，请告诉我威胁分数，它是否是云提供商，以及它是否看起来像中继。

查找谁拥有IP

• 谁使用1.1.1.1，哪个ASN路由它？
• 对于AS24940，仅列出上游ASN编号。
• 这是IP任意播吗？宣布的路由前缀是什么：1.1.1.1

获取虐待联系人

• 对于IP 2.56.12.11，请给我滥用联系电子邮件、电话号码和组织。
• 我需要1.0.0.0的滥用联系人和涉及的网络路由。
• 对于此IP，请仅向我显示滥用联系方式：198.51.100.27

时区查找和转换

• 东京现在几点了？
• 将2026-03-07 09:30从纽约时间转换为东京时间。
• 肯尼迪机场的当前当地时间是什么时候？

日出、日落和月亮数据

• 给出2026年6月21日伦敦的日出和日落。
• 显示2026年3月10日至2026年03月15日卡拉奇的日出时间。
• 对于纽约，给我2026-07-17的月相和日长。

解析用户代理字符串

• 解析此用户代理：Mozilla/5.0（Macintosh；英特尔Mac OS X 10_11_2）AppleWebKit/601.3.9（KHTML，类似于Gecko）版本/9.0.2 Safari/601.3.9
• 批量解析这些用户代理，并告诉我每个代理的浏览器、操作系统和设备类型。
• 这个用户代理看起来像爬虫还是机器人？Mozilla/5.0（Linux；安卓6.0.1；Nexus 5X Build/MMB29P）苹果WebKit/537.36（KHTML，像壁虎一样）Chrome/40.2272.96移动Safari/537.36+http://www.google.com/bot.html)

示例答案和工具输出

下面的文本答案显示了客户可能会说什么。确切的措辞取决于模型。JSON块显示了原始工具输出，为了可读性而进行了修剪。

单IP查找

提示： 找到91.128.103.196，告诉我国家、城市、ASN和当地时间。

示例答案： 91.128.103.196在瑞典斯德哥尔摩。ASN是AS1257，由Tele2 Sverige AB运营。时区是欧洲/斯德哥尔摩，当地时间是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-02-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"]
  }
}

错误代码

所有工具都会返回结构化错误，而不是使服务器崩溃。API错误包括上游状态/消息加上 guidance 字段，因此MCP客户端可以告诉用户下一步要检查什么，而不仅仅是重复上游响应。

确切的状态代码可能因端点和请求模式而异。如果上游端点返回此表之外的状态，服务器不会猜测原因。它通过以下方式传递上游状态和消息 category: "undocumented_api_error" 并为MCP客户端添加了指导，以将响应解释为未记录的上游状态，而无需发明原因。

运作原理

这是一个封装了ipgeolocation.io v3 API的stdio MCP服务器。

运行时：

1. 您的MCP客户端启动服务器进程。
2. 客户端读取工具列表。
3. 当提示与工具匹配时，客户端会调用它。
4. 服务器验证输入，调用API，并返回结构化JSON。
5. 可缓存响应存储在进程内存中，因此重复的相同请求会跳过API调用。

lookup_company, lookup_currency，以及 lookup_network 是围绕完整IP查找响应部分的包装器。它们作为单独的工具存在，因此当用户只需要一条数据时，MCP客户端可以发现它们。

缓存

返回稳定数据（不是当前时间查找）的工具将其响应缓存在进程内存中。重复查找更快，不使用额外的积分。客户端重试不会生成重复的API调用。

• 进程级缓存，而不是客户端或模型内存
• 缓存条目的范围由API键确定，因此单独的MCP会话不会共享缓存的上游数据
• 默认TTL：5分钟(300000 ms）
• 服务器进程停止时缓存重置
• TTL到期时缓存未命中、参数更改或 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

环境变量

从源头构建

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

直接运行它：

IPGEOLOCATION_API_KEY= node dist/cli.js

与MCP检查员一起检查：

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

码头工人

docker build -t ipgeolocation-mcp .
docker run -e IPGEOLOCATION_API_KEY= ipgeolocation-mcp

测试

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

故障排除

客户端在更新后使用旧工具： 重新启动客户端并确认它加载了最新的npm版本。

401错误： 检查一下 IPGEOLOCATION_API_KEY 在您的配置中设置。有些工具只需付费，并在免费计划中返回401。域查找 lookup_ip 还需要付费计划。

423个错误： 你通过了一个私有/bogon IP 10.0.0.1 或 192.168.1.1。这些没有地理位置数据。

504超时： 上游API未及时响应。增加超时时间 IPGEOLOCATION_REQUEST_TIMEOUT_MS （默认值：15000毫秒，最大值：120000毫秒）。

定价

有关当前计划的详细信息、积分和定价，请参阅 IP地理定位定价页面.

链接

• IP地理定位网站
• IPGeolocation API文档
• IP地理定位定价
• 创建免费IPGeolocation API密钥
• 更新日志

许可证

麻省理工学院

隐私政策

阅读 IP地理定位隐私政策.