SurveyHub-MCP FastMCP server for FOFA, Quake, Hunter, ZoomEye, DayDayMap, Shodan, Censys, SecurityTrails, BinaryEdge, Netlas, and Onyphe cyberspace mapping platforms

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for POCO from gravatar.com POCO

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: helGayhub233
  • Tags binaryedge , censys , cyberspace , daydaymap , fofa , hunter , mcp , netlas , onyphe , osint , quake , security , securitytrails , shodan , zoomeye
  • Requires: Python >=3.10
Classifiers
Report project as malware

Project description

SurveyHub-MCP

基于 FastMCP 编写的网络空间测绘 MCP Server，聚合查询 FOFA、Quake、Hunter、ZoomEye、DayDayMap、Shodan、Censys、SecurityTrails、BinaryEdge、Netlas、Onyphe。

适合在 Claude Desktop、Cursor、Cherry Studio 等支持 MCP 的客户端中使用。

支持平台

平台 能力
FOFA 资产搜索、连续翻页、统计聚合、Host 聚合、账号信息
360 Quake 服务搜索、深度翻页、聚合查询、字段查询、账号信息
Hunter 个人版 资产搜索、批量任务、任务状态、结果下载、账号信息
Hunter 企业版 资产搜索、批量任务、任务状态、结果下载、结果拉取、账号信息
ZoomEye 资产搜索、账号信息
DayDayMap 资产搜索
Shodan 资产搜索、统计聚合、Host 详情、DNS 查询、账号信息
Censys 资产搜索、聚合统计、Host 详情、账号信息
SecurityTrails 域名信息、子域名枚举、DNS 历史、IP WHOIS
BinaryEdge 全域搜索、子域名枚举、账户信息
Netlas 互联网扫描搜索、DNS 搜索、IP WHOIS、账户信息
Onyphe 资产搜索、IP 摘要、域名摘要、账户信息

快速开始

通过 pip 安装

要求 Python >=3.10。用户无需 clone 源码，可直接从 PyPI 安装：

python -m pip install -U surveyhub-mcp

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

surveyhub-mcp

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_KEY": "fallback_hunter_key",
        "CN_HUNTER_PERSONAL_KEY": "your_hunter_personal_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key",
        "US_SHODAN_API_KEY": "your_shodan_api_key",
        "US_CENSYS_API_ID": "your_censys_api_id",
        "US_CENSYS_API_SECRET": "your_censys_api_secret",
        "US_SECURITYTRAILS_API_KEY": "your_securitytrails_api_key",
        "PT_BINARYEDGE_API_KEY": "your_binaryedge_api_key",
        "CY_NETLAS_API_KEY": "your_netlas_api_key",
        "FR_ONYPHE_API_KEY": "your_onyphe_api_key"
      }
    }
  }
}

只运行单个平台入口时：

fofa-mcp
quake-mcp
zoomeye-mcp
hunter-personal-mcp
hunter-enterprise-mcp
daydaymap-mcp
shodan-mcp
censys-mcp
securitytrails-mcp
binaryedge-mcp
netlas-mcp
onyphe-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_KEY": "fallback_hunter_key",
        "CN_HUNTER_PERSONAL_KEY": "your_hunter_personal_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key",
        "US_SHODAN_API_KEY": "your_shodan_api_key",
        "US_CENSYS_API_ID": "your_censys_api_id",
        "US_CENSYS_API_SECRET": "your_censys_api_secret",
        "US_SECURITYTRAILS_API_KEY": "your_securitytrails_api_key",
        "PT_BINARYEDGE_API_KEY": "your_binaryedge_api_key",
        "CY_NETLAS_API_KEY": "your_netlas_api_key",
        "FR_ONYPHE_API_KEY": "your_onyphe_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
uvx --from surveyhub-mcp shodan-mcp
uvx --from surveyhub-mcp censys-mcp
uvx --from surveyhub-mcp securitytrails-mcp
uvx --from surveyhub-mcp binaryedge-mcp
uvx --from surveyhub-mcp netlas-mcp
uvx --from surveyhub-mcp onyphe-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
uv run shodan-mcp
uv run censys-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_KEY": "fallback_hunter_key",
        "CN_HUNTER_PERSONAL_KEY": "your_hunter_personal_key",
        "CN_HUNTER_ENTERPRISE_KEY": "your_hunter_enterprise_key",
        "CN_DAYDAYMAP_API_KEY": "your_daydaymap_api_key"
      }
    }
  }
}

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

平台 单平台入口 必要环境变量
FOFA fofa-mcp CN_FOFA_KEY
Quake quake-mcp CN_QUAKE_KEY
ZoomEye zoomeye-mcp CN_ZOOMEYE_API_KEY
Hunter 个人版 hunter-personal-mcp CN_HUNTER_PERSONAL_KEY
Hunter 企业版 hunter-enterprise-mcp CN_HUNTER_ENTERPRISE_KEY
DayDayMap daydaymap-mcp CN_DAYDAYMAP_API_KEY
Shodan shodan-mcp US_SHODAN_API_KEY
Censys censys-mcp US_CENSYS_API_ID + US_CENSYS_API_SECRET
SecurityTrails securitytrails-mcp US_SECURITYTRAILS_API_KEY
BinaryEdge binaryedge-mcp PT_BINARYEDGE_API_KEY
Netlas netlas-mcp CY_NETLAS_API_KEY
Onyphe onyphe-mcp FR_ONYPHE_API_KEY

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

环境变量

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

环境变量 说明
CN_FOFA_KEY FOFA API Key
CN_FOFA_EMAIL FOFA Email，可选
CN_QUAKE_KEY 360 Quake API Key
CN_ZOOMEYE_API_KEY ZoomEye API Key
CN_HUNTER_KEY Hunter 通用 fallback API Key
CN_HUNTER_PERSONAL_KEY Hunter 个人版 API Key
CN_HUNTER_ENTERPRISE_KEY Hunter 企业版 API Key
CN_DAYDAYMAP_API_KEY DayDayMap API Key
US_SHODAN_API_KEY Shodan API Key
US_CENSYS_API_ID Censys API ID
US_CENSYS_API_SECRET Censys API Secret
US_SECURITYTRAILS_API_KEY SecurityTrails API Key
PT_BINARYEDGE_API_KEY BinaryEdge API Key
CY_NETLAS_API_KEY Netlas API Key
FR_ONYPHE_API_KEY Onyphe API Key

预留前缀（暂无对应模块）：FR_（LeakIX）、AE_（FullHunt）、KR_（Criminal IP）。

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
  • Shodan: https://account.shodan.io
  • Censys: https://search.censys.io/account/api
  • SecurityTrails: https://securitytrails.com/app/account/credentials
  • BinaryEdge: https://app.binaryedge.io/account
  • Netlas: https://app.netlas.io/profile/
  • Onyphe: https://www.onyphe.io/

工具列表

FOFA

工具 说明
fofa_search 常规资产搜索
fofa_search_next 连续翻页搜索
fofa_search_stats 统计聚合
fofa_host Host 聚合
fofa_user_info 账号信息

Quake

工具 说明
quake_user_info 用户信息
quake_filterable_fields 服务数据可筛选字段
quake_service_search 实时服务搜索
quake_service_scroll 深度翻页搜索
quake_search 兼容别名，等同于 quake_service_scroll
quake_aggregation_fields 聚合字段列表
quake_service_aggregation 服务聚合查询

ZoomEye

工具 说明
zoomeye_user_info 用户信息、订阅信息和积分情况
zoomeye_search 资产搜索

Hunter 个人版

工具 说明
hunter_personal_search 资产搜索
hunter_personal_batch_create 创建批量任务
hunter_personal_batch_status 查询批量任务状态
hunter_personal_batch_download 下载批量任务结果
hunter_personal_user_info 账号信息

Hunter 企业版

工具 说明
hunter_enterprise_search 资产搜索
hunter_enterprise_batch_create 创建批量任务
hunter_enterprise_batch_status 查询批量任务状态
hunter_enterprise_batch_download 下载批量任务结果
hunter_enterprise_batch_pull 拉取批量任务结果 JSON
hunter_enterprise_user_info 账号信息

DayDayMap

工具 说明
daydaymap_search 资产搜索

Shodan

工具 说明
shodan_search 资产搜索
shodan_search_count 搜索结果计数（不消耗额度）
shodan_host IP 主机详情
shodan_api_info API 配额信息
shodan_domain 域名信息（子域名+DNS 记录）
shodan_dns_resolve DNS 正向解析
shodan_dns_reverse DNS 反向解析

Censys

工具 说明
censys_search 资产搜索
censys_aggregate 聚合统计（端口/国家/服务分布）
censys_view_host IP 主机详情
censys_account 账号配额信息

SecurityTrails

工具 说明
securitytrails_domain 域名信息（DNS 记录+统计）
securitytrails_subdomains 子域名枚举
securitytrails_dns_history DNS 历史记录
securitytrails_ip IP WHOIS 查询

BinaryEdge

工具 说明
binaryedge_search 全域资产搜索
binaryedge_subdomains 子域名枚举
binaryedge_account 账户配额信息

Netlas

工具 说明
netlas_search 互联网扫描数据搜索（banner/HTTP/SSL）
netlas_domain DNS 记录搜索
netlas_whois_ip IP WHOIS 搜索
netlas_account 账户配额信息

Onyphe

工具 说明
onyphe_search OQL 资产搜索
onyphe_summary_ip IP 资产摘要（30天全类别聚合）
onyphe_summary_domain 域名资产摘要
onyphe_account 账户信息（许可证/信用额度）

请求限制

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

平台 工具 控制方式
FOFA fofa_search_stats 进程内节流，5 秒/次
FOFA fofa_host 进程内节流，1 秒/次
FOFA fofa_search, fofa_search_next 本地校验，返回 body 时 size <= 500
FOFA fofa_search, fofa_search_next 本地校验，返回 cert 或 banner 时 size <= 2000
Quake quake_service_search, quake_service_scroll 参数 schema 限制，size <= 500
Quake quake_service_aggregation 本地校验聚合字段最多 2 个，参数 schema 限制 size <= 10000
ZoomEye zoomeye_search 参数 schema 限制，pagesize <= 10000
Hunter 个人版 批量任务 工具描述提示平台限制：all <= 10，ip/domain/company <= 100
Hunter 企业版 批量任务 工具描述提示平台限制：all <= 10，ip/domain/company <= 10000
DayDayMap daydaymap_search 参数 schema 限制，page <= 10000、page_size <= 10000
Shodan 全部搜索工具 进程内节流，1 秒/次
Censys 全部搜索工具 进程内节流，1.1 秒/次（满足 1 并发限制）
SecurityTrails 全部搜索工具 进程内节流，1 秒/次
BinaryEdge 全部搜索工具 进程内节流，1 秒/次
Netlas 全部搜索工具 进程内节流，1 秒/次
Onyphe 全部搜索工具 进程内节流，1 秒/次

FOFA 的频率控制是单 MCP 进程内的内存节流；如果同时启动多个 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
  • docs/api/shodan_api.md
  • docs/api/censys_api.md
  • docs/api/securitytrails_api.md
  • docs/api/binaryedge_api.md
  • docs/api/netlas_api.md
  • docs/api/onyphe_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 工具
    shodan.py             # Shodan 工具
    censys.py             # Censys 工具
    securitytrails.py      # SecurityTrails 工具
    binaryedge.py          # BinaryEdge 工具
    netlas.py              # Netlas 工具
    onyphe.py              # Onyphe 工具
    common.py              # 共享编码、HTTP、错误处理和节流工具

开发

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

注意

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

许可证

MIT License，见 LICENSE。

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for POCO from gravatar.com POCO

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: helGayhub233
  • Tags binaryedge , censys , cyberspace , daydaymap , fofa , hunter , mcp , netlas , onyphe , osint , quake , security , securitytrails , shodan , zoomeye
  • Requires: Python >=3.10
Classifiers

Release history Release notifications | RSS feed

1.17.0

1.16.0

1.15.0

1.14.0

1.13.0

1.12.0

1.11.0

1.10.0

1.9.0

1.8.0

This version

1.7.0

1.6.0

1.5.0

1.4.0

1.3.0

1.2.0

1.1.0

1.0.2

1.0.1

1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

surveyhub_mcp-1.7.0-py3-none-any.whl (39.7 kB view details)

Uploaded Python 3

File details

Details for the file surveyhub_mcp-1.7.0-py3-none-any.whl.

File metadata

  • Download URL: surveyhub_mcp-1.7.0-py3-none-any.whl
  • Upload date:
  • Size: 39.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for surveyhub_mcp-1.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 bffe75b16ead2cffe38116c014f7731d9402e8f97920eba50932da45add76a8d
MD5 56141d537dc9b2f90981c57b34b15cb6
BLAKE2b-256 234b09c24b25c13e20aef42edf0e8425be2d6b40f58c6d8ad014b8ca8ec21d88

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page