ICPQuery-MCP

基于官方 MCP Python SDK 2.x 编写的 ICP 备案查询 MCP Server，支持网站、App、小程序、快应用备案信息和违法违规黑名单查询

支持类型

快速开始

使用 uvx（推荐）

要求 Python >=3.10。无需 clone 或预先安装，在 MCP 客户端中直接运行 PyPI 包：

{
  "mcpServers": {
    "icp-query": {
      "command": "uvx",
      "args": [
        "icpquery-mcp"
      ],
      "env": {
        "ICP_RATE_LIMIT_QUERY_PER_MIN": "5",
        "ICP_RATE_LIMIT_BLACKLIST_PER_MIN": "3",
        "ICP_PROXY_TUNNEL": ""
      }
    }
  }
}

使用 pip

python -m pip install -U icpquery-mcp
icpquery-mcp

从源码运行

要求 Python >=3.10，MCP Python SDK >=2.0.0,<3。

git clone https://github.com/helGayhub233/ICPQuery-MCP.git
cd ICPQuery-MCP
uv sync
uv run icpquery-mcp

MCP 配置

从源码运行时，推荐在 MCP 客户端中固定项目目录：

{
  "mcpServers": {
    "icp-query": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ICPQuery-MCP",
        "run",
        "icpquery-mcp"
      ],
      "env": {
        "ICP_RATE_LIMIT_QUERY_PER_MIN": "5",
        "ICP_RATE_LIMIT_BLACKLIST_PER_MIN": "3",
        "ICP_PROXY_TUNNEL": ""
      }
    }
  }
}

如果已经通过 pip 安装，也可以直接使用入口命令：

{
  "mcpServers": {
    "icp-query": {
      "command": "icpquery-mcp",
      "args": []
    }
  }
}

MCP 协议兼容性

服务使用官方 MCPServer API，同时兼容 2026-07-28 新协议和 2025-11-25 旧协议。SDK 会根据客户端自动选择 server/discover 或传统 initialize 流程，无需启动两套服务。

本地 CLI

icpquery check-env
icpquery config-show
icpquery query baidu.com
icpquery query 微信 -t app
icpquery query baidu.com -t bweb

环境变量

环境变量使用 ICP_ 前缀命名规范。

默认配置见 config.example.yml；可直接复制的 MCP 客户端配置见 mcp.json.example。config_show 和 check_environment 会将已配置的代理地址 显示为 <configured>，避免把代理凭据带入 MCP 对话上下文。

工具列表

查询参数

icp_query

icp_blacklist

请求限制

项目会在 MCP 服务进程内做本地保护，避免客户端并发请求直接打到目标接口。

Qoder 等 MCP 客户端可能默认并发触发 5/10 个 tool call；本项目内部会强制串行化，同一进程内前一个查询完整结束后，下一个查询才会访问目标接口。

项目结构

src/
  icpquery_mcp/
    server.py              # MCP 入口
    cli.py                 # 本地 CLI
    core/
      client.py            # 工信部接口调用、token、验证码和详情补全
      captcha.py           # 滑块验证码偏移识别
      config.py            # YAML 和环境变量配置
      ratelimit.py         # 频率控制和单例队列保护
    tools/
      local_tools.py       # MCP 工具与 CLI 复用封装

发布验证

PYTHONPYCACHEPREFIX=/tmp/icpquery-pyc python -m compileall src
icpquery check-env
icpquery config-show
uv build
npx --yes @modelcontextprotocol/inspector --cli icpquery-mcp --method tools/list

最近一次官方 Inspector 扫描结果见 MCP_INSPECTOR_REPORT.md。

注意事项

本项目仅供学习和技术研究使用，严禁用于任何商业或非法用途。

请只在合法授权范围内使用，并自行承担接口变化、验证码策略变化、目标风控或网络环境导致的失败风险。

许可证

MIT License，见 LICENSE。