IPinfo

IPinfo MCP 服务

官方 IPinfo MCP 服务可让 Claude 等 AI 助手回答有关 IP 地址的问题。询问某个 IP 所在的位置、所属的公司或网络，或它是否为 VPN、代理、Tor 出口节点或住宅代理，助手便会通过 IPinfo 数据进行查询。

它实现了 Model Context Protocol（MCP），这是 AI 助手用于连接外部工具的开放标准，因此可与任何兼容 MCP 的客户端配合使用。它支持 IPinfo Lite、Core、Plus 和 Residential Proxy 计划。

完整指南请参阅官方文档。

安装

你需要一个 IPinfo 账户。前往 ipinfo.io/signup 免费注册。

托管服务

将 MCP 客户端指向 https://mcp.ipinfo.io/（Streamable HTTP）。首次连接时，系统会要求你通过 OAuth 使用 IPinfo 账户登录。

本地服务（PyPI）

该服务以 ipinfo-mcp-server 的名称发布在 PyPI 上，并通过 stdio 运行，使用你的 API token 进行身份验证。安装 uv 后，将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "ipinfo": {
      "command": "uvx",
      "args": ["ipinfo-mcp-server"],
      "env": {
        "IPINFO_TOKEN": "<your-ipinfo-token>"
      }
    }
  }
}

Claude Desktop 扩展

从 最新的 GitHub 版本发布页下载 mcp.mcpb，并使用 Claude Desktop 打开。安装过程中，系统会要求你提供 API token。

MCP Registry

该服务已以 io.github.ipinfo/mcp 的名称列入 MCP Registry。

该服务也已列入 LightNow。

工具

工具	描述	计划要求
ipinfo_lookup	完整 IP 数据：地理位置、网络和元数据	任意；detailed: true 需要 Core/Plus
ipinfo_geolocate	地理位置	任意；detailed: true 需要 Core/Plus
ipinfo_asn	自治系统（网络归属）	任意；detailed: true 需要 Core/Plus
ipinfo_check_privacy	VPN、代理、中继、Tor、托管、任播、移动网络、卫星网络标记	付费计划
ipinfo_check_residential_proxy	住宅代理检测	住宅代理访问权限
ipinfo_quota	API 用量和剩余配额	任意

对于 token 所属计划无法访问的工具，会返回 ACCESS_DENIED 错误。

通用参数

除 ipinfo_quota 外，所有工具都接受 IP 列表，并支持分页：

参数	类型	默认值	说明
ips	string[]	必填	公网 IPv4 或 IPv6 地址。私有、环回、保留、多播和 bogon 地址会被拒绝，并在 validation_errors 中报告。
page	integer	1	结果集的页码，从 1 开始。小于 1 的值会调整为 1。
page_size	integer	25	每页解析的 IP 数量，上限为 1000。仅会获取请求页中的 IP，因此每次调用的页面越小，消耗的配额越少。

ipinfo_lookup、ipinfo_geolocate 和 ipinfo_asn 还接受：

参数	类型	默认值	说明
detailed	boolean	false	false 时查询 Lite 端点；true 时查询完整 lookup 端点，返回更多字段。

通用输出

基于 IP 的工具会返回：

字段	说明
results	以 IP 为键的对象，包含下方所述的工具专属数据。
errors	以 IP 为键的对象，包含 API 返回错误的 IP。这些 IP 不会出现在 results 中。
validation_errors	以输入值为键的对象，包含不是有效公网 IP 的值。仅在存在此类值时出现。
_pagination	total_results、page、page_size、total_pages、has_next、has_previous。
_meta	api_calls_made 和 from_cache。结果会缓存在内存中，因此重复查询不会消耗 API 配额。

如果整个请求失败（例如缺少或令牌无效），工具会改为返回一个错误对象，其中包含 code（ACCESS_DENIED、RATE_LIMITED、INVALID_TOKEN、NO_TOKEN、API_ERROR 或 UNKNOWN）、message 和 suggestion。

ipinfo_lookup

返回每个 IP 对应的原始 IPinfo API 响应。

• detailed: false（Lite）：ip、asn、as_name、as_domain、country、country_code、continent、continent_code。
• detailed: true（完整 lookup）：ip、hostname、geo（城市、地区、国家、大洲、坐标、时区、邮政编码）、as（ASN、名称、域名、类型）、anonymous（代理、中继、Tor、VPN）、mobile，以及 is_anonymous、is_anycast、is_hosting、is_mobile、is_satellite 标记。部分字段仅在 Plus 版本中提供。

ipinfo_geolocate

每个 IP 返回：ip、country、country_code、continent、continent_code。设置 detailed: true 时，还会返回 city、region、region_code、latitude、longitude、timezone、postal_code。

ipinfo_asn

每个 IP 返回：ip、asn、name、domain。设置 detailed: true 时，还会返回 type（isp、hosting、business、education）和 last_changed。

ipinfo_check_privacy

每个 IP 返回：ip、is_anonymous、anonymous（is_proxy、is_relay、is_tor、is_vpn）、is_anycast、is_hosting、is_mobile、is_satellite。

ipinfo_check_residential_proxy

按 IP 返回：ip 和 is_residential_proxy。对于住宅代理，还会返回 service（代理服务名称）、last_seen（日期）和 percent_days_seen。

ipinfo_quota

无需参数。返回 token（使用 OAuth 连接时省略）、requests（包含 day、month、limit、remaining），以及 features 下每项功能的配额。

配置

可通过环境变量配置服务：

变量	默认值	说明
IPINFO_TOKEN		API 令牌（stdio 传输；使用 HTTP 时，令牌来自请求）
IPINFO_API_BASE_URL	https://api.ipinfo.io	api.ipinfo.io 端点的基础 URL
IPINFO_LEGACY_BASE_URL	https://ipinfo.io	旧版 ipinfo.io 端点（例如 /me）的基础 URL
IPINFO_CACHE_TTL	3600	缓存的 IP 结果保持新鲜的秒数
IPINFO_TRANSPORT	stdio	传输类型（stdio 或 http）
HOST	0.0.0.0	HTTP 主机（仅用于 http 传输）
PORT	8000	HTTP 端口（仅用于 http 传输）
IPINFO_OAUTH_ISSUER		接受其访问令牌的 OAuth 颁发者；未设置时，OAuth 处于关闭状态
IPINFO_MCP_RESOURCE_URL		此服务的公开 URL；设置 IPINFO_OAUTH_ISSUER 时必需
IPINFO_OAUTH_JWKS_URI	<issuer>/.well-known/jwks.json	颁发者发布签名密钥的位置

使用 http 传输时，每个请求都通过自己的 Authorization: Bearer <token> 标头进行身份验证。

设置 IPINFO_OAUTH_ISSUER 会为 http 传输启用 OAuth。随后，服务会在 /.well-known/oauth-protected-resource 发布颁发者信息，对没有有效凭据的请求返回 401 Unauthorized，并根据颁发者的签名密钥验证访问令牌。经过验证的访问令牌会代替 API 令牌发送到 IPinfo API。API 令牌仍可照常使用。

反馈

• **错误和功能请求：**在 GitHub Issues 上提交问题。
• **安全漏洞：**请勿公开提交问题；请遵循安全政策。
• **关于 IPinfo 账户或套餐的问题：**联系 [email protected]。

贡献

欢迎贡献。有关工作流以及更改必须满足的要求，请参阅 CONTRIBUTING.md。

开发

前置条件

• Python 3.14+
• uv

设置

uv sync --dev
cp .env.example .env
# Add your IPinfo token to .env

运行服务

服务支持两种传输方式：stdio（默认）和 HTTP。

# stdio (default, used by MCP clients)
uv run ipinfo-mcp-server

# HTTP
IPINFO_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run ipinfo-mcp-server

测试

# All tests
uv run pytest

# Integration tests (requires IPINFO_TOKEN)
uv run pytest tests/integration/

集成测试会调用真实的 IPinfo API，并且只验证响应结构（不对具体值进行断言）。这些测试要求设置 IPINFO_TOKEN，否则会被跳过。

类型检查

uv run pyright

代码检查

uv run ruff check .
uv run ruff format .