IP Geolocation MCP Server

IP Geolocation MCP Server

一个 Model Context Protocol 服务，可向 AI Agent 提供 ipinfo.io API。对 IPv4 和 IPv6 地址进行地理定位、识别 ISP 和 ASN、检测 VPN／代理／Tor 出口节点，并为一组 IP 生成交互式地图。

安装

如果还没有 IPInfo API 令牌，请前往 https://ipinfo.io/signup 注册免费令牌。此服务在没有令牌的情况下也能运行（免费 Lite 套餐——提供国家和 ASN 基本信息），但大多数字段都需要令牌。

Claude Desktop（一键安装包）

从最新版本下载 .mcpb 安装包并打开，即可在 Claude Desktop 中安装。你可以在安装对话框中设置 IPINFO_API_TOKEN（以及可选的缓存配置）；令牌留空即可使用免费 Lite 套餐。此安装包使用 uv 启动服务，因此必须安装 uv，并确保它位于系统 PATH 中（图形界面应用不会继承 shell 的 PATH）。

其他 MCP 客户端

大多数 MCP 客户端接受以下值：

字段	值
命令	uvx
参数	mcp-server-ipinfo
环境变量	IPINFO_API_TOKEN = <YOUR TOKEN>

开发版本

如需运行 main 分支中的最新版本：

字段	值
命令	uvx
参数	--from、git+https://github.com/briandconnelly/mcp-server-ipinfo、mcp-server-ipinfo
环境变量	IPINFO_API_TOKEN = <YOUR TOKEN>

工具

• ipinfo_lookup_my_ip() — 对调用客户端自身的 IP 进行地理定位。不接受参数。对于 stdio 传输，结果反映的是此服务的出站 IP，而非最终用户的 IP。
• ipinfo_lookup_ips(ips, detail="summary") — 对一个或多个指定 IP 进行地理定位。默认使用 detail="summary"，该选项会省略较大的嵌套数据块（continent、flags、currency、abuse、domains），以节省批量查询令牌；传入 detail="full" 可获取所有字段。每次调用最多支持 500,000 个 IP。无效或特殊用途地址（私有地址、环回地址等）会通过 ctx.warning() 过滤并从结果列表中排除，上游查询失败的 IP 也会如此；可将返回的 IPDetails.ip 值与输入进行匹配，以识别被排除的 IP。如果所有查询都失败，则会引发临时 api_error。
• ipinfo_summarize_ips(ips, group_by=("country", "asn"), top_n=50) — 对一批 IP 进行地理定位并汇总，按国家、大洲、ASN 和／或隐私标记生成固定大小的计数和百分比。适用于逐条 IP 记录会浪费上下文的大型日志分析任务。返回已映射、已跳过和失败的数量，以及数量上限为 top-N 的分组。
• ipinfo_check_residential_proxy(ip) — 检查 IP 是否为已知的住宅代理出口节点。标记为 enterprise——需要 IPInfo 住宅代理附加服务。
• ipinfo_generate_map_url(ips) — 为一组 IP 创建交互式 ipinfo.io 地图。返回包含 URL、地图所含 IP 数量、被过滤 IP（附原因，最多显示 100 个）以及 truncated 标记的 MapResult。

套餐等级

等级	可用字段
Free Lite（无令牌）	country、country_code、continent、ASN 基本信息
Core	完整地理定位、ASN 详情、隐私／VPN／代理／Tor／托管标记
Plus	增加运营商和公司数据
Enterprise	增加域名和滥用联系信息
住宅代理附加服务	启用 ipinfo_check_residential_proxy。在 Enterprise 套餐之外单独出售，默认不包含。

错误

每个工具都会引发 ToolError，其消息是 JSON 编码的信封，包含稳定的 code（invalid_ip_address、special_ip_unsupported、no_valid_ips、too_many_ips、auth_invalid、auth_insufficient_scope、quota_exceeded、timeout、api_error、unknown_error）、temporary 标志、可选的 retry_after_ms、repair 提示以及用于关联请求的 request_id。Agent 应将消息解析为 JSON，并根据 code 进行分支处理。每个工具还会通过 meta.error_codes 声明它可能引发的错误代码子集，因此可以通过工具自省查看分支集合。

配置

环境变量

变量	描述	默认值
IPINFO_API_TOKEN	IPInfo API 令牌。未设置时，服务将以免费 Lite 模式运行。	未设置（Lite）
IPINFO_CACHE_TTL	每个 IP 的缓存有效期，单位为秒。缓存结果会保留其原始 ts_retrieved 时间戳。	3600
IPINFO_CACHE_SIZE	最早缓存条目优先淘汰前的最大缓存条目数。	4096

许可证

MIT 许可证——请参阅 LICENSE。发布历史请参阅 CHANGELOG.md。

免责声明

本项目与 IPInfo 无关联。