FindIP

FindIP MCP 服务

向助手询问 IP 地址或存在风险的会话，并从 FindIP 获取答案。

@findip/mcp 是一个用于 FindIP 的 Model Context Protocol 服务。它为 Claude、Cursor 和其他 MCP 客户端提供 IP 情报和 FindIP Shield 风险信号。它通过 stdio 在本地运行，且只读取数据。

工具

工具	功能	密钥
lookup_ip	查询 IP 的国家、城市、ISP 和 ASN，以及风险信号：VPN、代理、Tor、中继、托管、扫描器、恶意来源记录、威胁评分	API 密钥
verify_session	对 Shield 会话进行服务端风险检查：评分、建议、质询状态、IP 和网络轮换情况	站点密钥
list_shield_sites	列出你的 Shield 站点及其今日事件数和风险事件数	API 密钥
recent_risky_events	查看站点近期高风险事件，例如“本周有哪些高风险流量访问了我的注册表单？”	API 密钥
explain_event	用通俗语言解释单个事件：来源、触发的信号以及建议的处理方式	API 密钥

这五种工具均为只读工具。docs/BACKEND.md 列出了每种工具对应的 FindIP 端点。

设置

你需要 Node.js 18.17 或更高版本，以及 FindIP API 密钥。可在 findip.net 免费获取密钥。

Claude Code

claude mcp add findip --env FINDIP_API_KEY=your_api_key -- npx -y @findip/mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json（“Settings”“Developer”“Edit Config”），然后重启 Claude Desktop：

{
  "mcpServers": {
    "findip": {
      "command": "npx",
      "args": ["-y", "@findip/mcp"],
      "env": {
        "FINDIP_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor

将以下内容添加到 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "findip": {
      "command": "npx",
      "args": ["-y", "@findip/mcp"],
      "env": {
        "FINDIP_API_KEY": "your_api_key"
      }
    }
  }
}

配置

变量	用途
FINDIP_API_KEY	你的 FindIP API 密钥。lookup_ip、list_shield_sites、recent_risky_events 和 explain_event 均需要此密钥。
FINDIP_SHIELD_SECRET_KEY	某个 Shield 站点的密钥（sec_...）。verify_session 需要此密钥。可在 Shield 控制面板的站点设置中找到。
FINDIP_SHIELD_ACCOUNT_API	设为 0 可关闭三个 Shield 账户工具，此时 API 密钥仅用于 IP 查询。默认开启。
FINDIP_TIMEOUT_MS	请求超时时间。默认值为 15000。
FINDIP_API_BASE_URL、FINDIP_SHIELD_BASE_URL、FINDIP_PORTAL_BASE_URL	覆盖 FindIP 主机地址，用于测试。

Shield 账户工具每个账户每分钟允许 60 次请求。使用错误密钥重复请求将被拦截 10 分钟。

密钥仅从环境变量中读取。它们不会作为工具参数传入，也不会出现在工具输出或错误消息中。

示例

• “查询 203.0.113.9。它是 VPN 还是托管服务提供商？”
• “验证 Shield 会话 sess_8f2c，并告诉我它被标记的原因。”
• “本周有哪些高风险流量访问了我的注册表单？”
• “解释 shop.example 上的事件 5b1e...。我需要担心吗？”

如何解读结果

FindIP 会报告风险信号。VPN、托管网络或高评分反映的是连接情况，而非连接背后的人。利用这些信号来决定是否要进一步查看、增加一道步骤或进行人工审核。

Shield 浏览器 SDK 会收集信号，并可在页面中增加操作阻力，但浏览器可能被脚本控制或绕过，因此它不是安全边界。重要决策应由你的服务端作出：在允许、发起质询或拦截之前，从后端调用服务端验证（即 verify_session 使用的端点）。risk_status: "unknown" 表示没有 IP 情报；应将其视为未知，而非安全。

隐私

• 服务仅与 FindIP 通信：api.findip.net、shield.findip.net 和 www.findip.net。
• Shield 工具不会返回终端用户身份信息（电子邮件、用户 ID 及其哈希值）。FindIP 会在数据离开其服务器前将这些信息移除。
• 站点列表仅提供简要摘要，不包含站点密钥和设置。
• 不收集遥测信息，也不会将任何内容写入磁盘。

开发

npm install
npm run typecheck
npm test        # vitest, all HTTP mocked
npm run build

许可证

MIT