SurveyHub-MCP

聚合 FOFA、Quake、Hunter、ZoomEye 与 DayDayMap 的空间测绘 MCP Server

支持平台

快速开始

通过 pip 安装

要求 Python >=3.10，MCP Python SDK >=2.0.0,<3。用户无需 clone 源码，可直接从 PyPI 安装：

python -m pip install -U surveyhub-mcp

安装后可直接启动聚合 MCP Server：

surveyhub-mcp

服务同时兼容 MCP 2026-07-28 和 2025-11-25；SDK 会根据客户端自动选择 server/discover 或传统 initialize 流程。

MCP 客户端配置：

{
  "mcpServers": {
    "surveyhub": {
      "command": "surveyhub-mcp",
      "args": [],
      "env": {
        "CN_FOFA_KEY": "your_fofa_key",
        "CN_FOFA_EMAIL": "optional_fofa_email",
        "CN_QUAKE_KEY": "your_quake_key",
        "CN_ZOOMEYE_API_KEY": "your_zoomeye_api_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key"
      }
    }
  }
}

只运行单个平台入口时：

fofa-mcp
quake-mcp
zoomeye-mcp
hunter-personal-mcp # 个人版
hunter-enterprise-mcp # 企业版
daydaymap-mcp

通过 uvx 免安装运行

如果不想提前安装，也可以在 MCP 客户端中使用 uvx 直接运行 PyPI 包：

{
  "mcpServers": {
    "surveyhub": {
      "command": "uvx",
      "args": [
        "surveyhub-mcp"
      ],
      "env": {
        "CN_FOFA_KEY": "your_fofa_key",
        "CN_FOFA_EMAIL": "optional_fofa_email",
        "CN_QUAKE_KEY": "your_quake_key",
        "CN_ZOOMEYE_API_KEY": "your_zoomeye_api_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key"
      }
    }
  }
}

只运行单个平台入口时：

uvx --from surveyhub-mcp fofa-mcp
uvx --from surveyhub-mcp quake-mcp
uvx --from surveyhub-mcp zoomeye-mcp
uvx --from surveyhub-mcp hunter-personal-mcp
uvx --from surveyhub-mcp hunter-enterprise-mcp
uvx --from surveyhub-mcp daydaymap-mcp

从源码运行

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

也可以只启动单个平台：

uv run fofa-mcp
uv run quake-mcp
uv run zoomeye-mcp
uv run hunter-personal-mcp
uv run hunter-enterprise-mcp
uv run daydaymap-mcp

MCP 配置

从源码运行时，推荐使用 uv --directory 固定项目目录。使用 PyPI 包时可直接参考上方 pip 或 uvx 配置。

{
  "mcpServers": {
    "surveyhub": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/SurveyHub-MCP",
        "run",
        "surveyhub-mcp"
      ],
      "env": {
        "CN_FOFA_KEY": "your_fofa_key",
        "CN_FOFA_EMAIL": "optional_fofa_email",
        "CN_QUAKE_KEY": "your_quake_key",
        "CN_ZOOMEYE_API_KEY": "your_zoomeye_api_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key"
      }
    }
  }
}

只使用某一个平台时，把 args 最后一个命令替换为对应入口，并只保留对应平台的 Key。

mcp.json.example 和 .env.example 提供了可直接修改的示例。

Hunter 版本路由

聚合入口会按 MCP 子进程实际收到的凭据选择 Hunter 工具族：只配置 CN_HUNTER_ENTERPRISE_KEY 时仅暴露 hunter_enterprise_*，只配置 CN_HUNTER_PERSONAL_KEY 时仅暴露 hunter_personal_*。共享的 CN_HUNTER_KEY 无法表明账户版本，因此会保留两组工具供调用者明确选择；未配置 Hunter Key 时也会保留两组 schema，用于暴露配置要求。

一般只应选择下列一种配置，不要把占位值同时填入三个变量：

同时设置共享 CN_HUNTER_KEY 和任一版本专用 Key，也可能使两组工具同时 出现，因此新配置应优先使用版本专用变量。

如果已配置企业版仍提示未配置，请检查 Key 是否放在 MCP 客户端的 mcpServers.<name>.env 中，而不是只存在于另一个终端。环境变量修改后必须重启 MCP 子进程。企业版也可直接使用 hunter-enterprise-mcp，该入口只暴露 6 个企业版工具，能进一步避免 Agent 误选个人版。如果仍调用到错误版本， 返回的 error.type=wrong_hunter_edition 和 error.details.recommended_tool 会指明已配置版本及 应改用的工具；不应将该错误概括为“Hunter 未配置”。

环境变量

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

API Key 获取入口：

• FOFA: https://fofa.info
• Quake: https://quake.360.net
• ZoomEye: https://www.zoomeye.org
• Hunter: https://hunter.qianxin.com
• DayDayMap: https://www.daydaymap.com

工具列表

下表是项目的完整能力集，不代表每个运行实例都会暴露全部工具。Hunter 工具会按 上述凭据版本动态选择，单平台入口则只暴露对应平台的工具。

工具返回结构化结果：成功时包含 ok=true、platform 和 data 或 text；失败时包含 ok=false、platform 和 error。meta.execution 还会返回 request_id、脱敏请求指纹、传输状态、重试安全性、配额风险与数据完整性，便于 AI 区分“确认空结果”与“执行结果未知”。

计费型资产搜索默认使用 retry_mode=safe_only：仅在请求确认未发送的连接或连接池失败时自动重试；写入或读取超时会返回 final_state=indeterminate，不会自动重发。相同指纹的请求在未知状态后 60 秒内会被请求账本抑制；只有明确接受重复扣费风险时才应设置 force_retry=true。

资源提示

服务会暴露查询语法和 API 文档资源，URI 前缀为 surveyhub://reference/，例如：

• surveyhub://reference/fofa-syntax
• surveyhub://reference/quake-syntax
• surveyhub://reference/hunter-syntax
• surveyhub://reference/zoomeye-syntax
• surveyhub://reference/daydaymap-api

聚合入口额外提供两个 Prompt：

• surveyhub_search_plan：根据目标和平台生成资产搜索计划
• surveyhub_query_help：检查并优化指定平台查询语句

请求限制

项目会对可在本地判断的参数做校验或节流。账号等级、积分额度、CSV 文件内容等仍以平台返回为准。

搜索响应的顶层 meta 包含 MCP 实际执行信息，例如 original_query、executed_query、attempts 和 partial_data；顶层 warnings 保留不会使请求失败、但可能影响完整性的供应商或参数提示。

FOFA 和 Quake 的频率控制、以及全部平台的熔断状态保存在单 MCP 进程内；Hunter 频率控制会按 API Key 通过本地 SQLite 在多个 MCP 进程之间共享。

API 文档

已整理的接口文档位于 docs/api/：

• docs/api/fofa_api.md
• docs/api/quake_api.md
• docs/api/zoomeye_api.md
• docs/api/hunter_personal_api.md
• docs/api/hunter_enterprise_api.md
• docs/api/daydaymap_api.md

版本发布和迭代记录见 CHANGELOG.md。

项目结构

src/
  surveyhub_mcp/
    server.py             # 聚合 MCP 入口
    fofa.py               # FOFA 工具
    quake.py              # Quake 工具
    zoomeye.py            # ZoomEye 工具
    hunter_personal.py    # Hunter 个人版工具
    hunter_enterprise.py  # Hunter 企业版工具
    daydaymap.py          # DayDayMap 工具
    reference.py          # MCP resources 和 prompts
    common.py             # 共享编码、HTTP、错误处理和节流工具

手动编译

uv sync
uv run python -m compileall src/surveyhub_mcp
uv build --wheel

注意事项

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

请只在合法授权范围内使用本项目，并遵守各平台的 API 服务条款和额度限制。

许可证

MIT License，见 LICENSE。