Skip to main content
Glama

Qianxin Hunter MCP Server

一个用于查询 Qianxin Hunter 网络空间测绘平台(奇安信鹰图平台)的 MCP (Model Context Protocol) 服务器。

功能特性

  • 🔍 查询资产: 支持按照语法进行资产查询

  • 🗂️ 批量查询: 支持批量 IP、Domain、Company 等查询,支持从本地上传批量查询文件

  • 📤 导出任务创建: 支持创建导出任务(异步任务)

  • 🔄 导出进度查询: 支持查询导出任务进度

  • 📥 导出文件下载: 下载结果文件到本地

  • ⚙️ 环境变量配置: 通过环境变量配置 API-KEY、默认查询字段、默认导出字段、文件下载目录

Related MCP server: FOFA MCP Server

安装 MCP Server

配置 mcp.json

简单快速配置(推荐)

{
  "mcpServers": {
    "hunter-mcp": {
      "command": "uvx",
      "args": [
        "hunter-mcp"
      ],
      "env": {
        "HUNTER_API_KEY": "xxx"
      }
    }
  }
}

或先安装 cli,再配置 json

# 使用 uv 从 PyPI 下载安装 cli
uv tool install hunter-mcp
{
  "mcpServers": {
    "hunter-mcp": {
      "command": "hunter-mcp",
      "args": [],
      "env": {
        "HUNTER_API_KEY": "xxx"
      }
    }
  }
}

或先下载/安装项目,再配置 json

# 使用 pip 从 PyPI 下载安装 Mcp
pip install hunter-mcp
#pip install --index-url https://pypi.org/simple hunter-mcp
# 从 github 下载安装 Mcp,使用 pip 安装
git clone https://github.com/PiggyHurry/hunter-mcp.git
cd hunter-mcp
pip install .
# pip install -e . # Editable
#pip show hunter-mcp
{
  "mcpServers": {
    "hunter-mcp": {
      "command": "uv",
      "args": [
        "run",
        "hunter-mcp"
      ],
      "env": {
        "HUNTER_API_KEY": "xxx"
      }
    }
  }
}

配置环境变量

{
  "mcpServers": {
    "hunter-mcp": {
      "command": "uvx",
      "args": [
        "hunter-mcp"
      ],
      "env": {
        "HUNTER_API_KEY": "xxx",
        "DEFAULT_SEARCH_FIELDS": "ip,port,domain",
        "DEFAULT_BATCH_FIELDS": "ip,port,domain",
        "DEFAULT_BATCH_SAVE_DIR": "/path/to/download/dir/"
      }
    }
  }
}

环境变量说明

DEFAULT_SEARCH_FIELDS: 检索接口默认返回字段。非必须。
DEFAULT_BATCH_FIELDS: 批量/导出接口默认返回字段。非必须。
DEFAULT_BATCH_SAVE_DIR: 导出文件默认下载目录。非必须。

hunter检索接口和批量/导出接口,默认返回权限内所有可导出字段。
对于检索接口,响应结果会直接返回给大模型,可能会导致模型token消耗过多。可在对话中指定字段,或者配置默认字段的环境变量,以降低token消耗。
    字段优先级:对话中指定字段 > 模型自主选择字段 > 环境变量默认配置字段 > 默认权限内所有字段
对于导出任务,下载接口返回的文件会保存到本地,然后仅将保存地址返回给大模型,不会造成模型token消耗过多。
    如无必要,不要让大模型分析下载后的文件,除非token用不完。

获取 api-key

在 claude code 中配置

# Add hunter mcp
claude mcp add hunter-mcp --env HUNTER_API_KEY=xxx --env DEFAULT_SEARCH_FIELDS=ip,port,domain -- uvx hunter-mcp
# List installed servers
claude mcp list
# Edit hunter mcp
vim ~/.claude.json
{
  "mcpServers": {
    "hunter-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hunter-mcp"
      ],
      "env": {
        "HUNTER_API_KEY": "xxx"
      }
    }
  }
}

在 opencode 中配置

# Add hunter mcp
opencode mcp add
# List installed servers
opencode mcp list
# Edit hunter mcp
vim ~/.config/opencode/opencode.json
{
  "mcp": {
    "hunter-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "hunter-mcp"
      ],
      "environment": {
        "HUNTER_API_KEY": "xxx"
      }
    }
  }
}

MCP 工具说明

1. Hunter 查询 (hunter_search)

主要参数:

  • search: 查询语法(如ip="1.1.1.1"

  • page: 页码(默认 1)

  • page_size: 每页资产条数(可选:10/50/100,默认 10)

  • start_time: 开始时间(格式:YYYY-MM-DD)

  • end_time: 结束时间(格式:YYYY-MM-DD)

  • is_web: 资产类型,1代表”web资产“,2代表”非web资产“,3代表”全部“

  • status_code: 状态码列表,以逗号分隔,如”200,401“

  • fields: 返回字段

2.1. Hunter 批量查询/导出 (hunter_batch_task_create)

主要参数:

  • search: 查询语法(如ip="1.1.1.1"

  • file_path: 包含检索目标的本地 CSV 文件路径(与 search 二选一提供)。

  • start_time: 开始时间(格式:YYYY-MM-DD)

  • end_time: 结束时间(格式:YYYY-MM-DD)

  • is_web: 资产类型,1代表”web资产“,2代表”非web资产“,3代表”全部“

  • status_code: 状态码列表,以逗号分隔,如”200,401“

  • fields: 返回字段

  • search_type: 上传文件类型,枚举值:all、ip、domain、company

  • assets_limit: 预期导出的资产数量(限制导出条数)

2.2. Hunter 批量查询/导出进度查询 (hunter_batch_task_progress)

主要参数:

  • task_id: 创建批量任务时返回的任务 ID。

2.3. Hunter 批量查询/导出CSV结果下载 (hunter_batch_task_result_download)

主要参数:

  • task_id: 创建批量任务时返回的任务 ID。

  • save_dir: 可选。保存文件的目录。如果未提供,将尝试从环境变量里获取默认目录。

  • file_name: 可选。保存的文件名。如果未提供,将尝试使用服务器返回的文件名。

Hunter 语法简介

匹配运算符:

  • = - 模糊查询,查询包含关键词的资产

  • == - 精确查询,查询有且仅有关键词的资产

  • != - 模糊剔除,剔除包含关键词的资产。使用 !="" 可查询值不为空的情况

  • !== - 精确剔除,剔除有且仅有关键词的资产

逻辑运算符:

  • && - 与(AND)

  • || - 或(OR)

  • () - 括号内表示查询优先级最高

查询示例:

# 模糊匹配
domain="example"
web.body="admin"

# 精确匹配
domain=="example.com"
web.title=="login"

# 模糊剔除
web.body!="admin"

# 精确剔除
domain!=="example.com"

# 查询值不为空
web.title!==""
is_domain="true"

# 逻辑 AND(&&)
ip="1.1.1.1" && is_domain="false"
domain="example.com" && header.status_code="200"

# 逻辑 OR(||)
domain="example.com" || domain="test.com"
web.title="admin" || web.title="login"

# 优先级控制
(web.title="admin" || web.title="login") && ip.tag="CDN"

使用案例(技巧)

1、从Hunter查询 ip="1.1.1.1" && port=80 的测绘资产
预期:(1)Tool: hunter_search {search: "ip=\"1.1.1.1\" && port=80"}

2、从Hunter查询 ip="1.1.1.1" && port=53 的测绘资产,fields="ip,port,domain,banner"
预期:(1)Tool: hunter_search {search: "ip=\"1.1.1.1\" && port=53", fields="ip,port,domain,banner"}
注意:fields参数可省略,默认返回权限内所有字段。优先级:对话中指定字段 > 模型自主选择字段 > 环境变量默认配置字段 > 默认权限内所有字段

3、从Hunter查询 app="OpenClaw" 2026-03-10 更新的资产数量
预期:(1)Tool: hunter_search {search: "ip=\"1.1.1.1\" && port=53", start_time="2026-03-10", end_time="2026-03-10"}

4、从Hunter查询 app="OpenClaw" 从2026年3月5日到2026年3月10日之间的资产变化趋势,每个日期对应的资产数为该日期往前推一个月的资产。然后帮我整理一个该趋势变化的表格。接口限速2s一次。
预期:(1)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-05", end_time="2026-03-05"}
     (2)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-06", end_time="2026-03-06"}
     (3)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-07", end_time="2026-03-07"}
     (4)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-08", end_time="2026-03-08"}
     (5)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-09", end_time="2026-03-09"}
     (6)Tool: hunter_search {search: "app=\"OpenClaw\"", start_time="2026-02-10", end_time="2026-03-10"}
注意:接口有限速,连续/并发调用工具可能会触发限速,请在对话中说明限速

5、从Hunter导出 app="OpenClaw" 2026-03-10 更新的资产
预期:(1)Tool: hunter_search_batch {search: "app=\"OpenClaw\"", start_time="2026-03-10", end_time="2026-03-10"}
     (2)Tool: hunter_search_batch_process {task_id: 123456}
     (.)Tool: hunter_search_batch_process {task_id: 123456} ... until process 100%
     (3)Tool: hunter_search_batch_download {task_id: 123456} ... until download finish
注意:若未在对话中说明下载目录,则尽量在环境变量中配置默认下载目录

6、从Hunter导出 app="OpenClaw" 2026-03-10 更新的资产,导出权限内所有可导出字段,保存到 /path 目录
预期:(1)Tool: hunter_search_batch {search: "app=\"OpenClaw\"", start_time="2026-03-10", end_time="2026-03-10", "fields":""}
     (2)Tool: hunter_search_batch_process {task_id: 123456}
     (.)Tool: hunter_search_batch_process {task_id: 123456} ... until process 100%
     (3)Tool: hunter_search_batch_download {task_id: 123456, save_dir="/path"} ... until download finish

7、从Hunter导出 /path/ip.csv 文件对应的测绘资产,导出类型选择ip,文件保存到 /path 目录
预期:(1)Tool: hunter_search_batch {file_path: "/path/ip.csv", search_type="ip"}
     (2)Tool: hunter_search_batch_process {task_id: 123456}
     (.)Tool: hunter_search_batch_process {task_id: 123456} ... until process 100%
     (3)Tool: hunter_search_batch_download {task_id: 123456, save_dir="/path"} ... until download finish

许可证

MIT License

Available Tools

4 tools
hunter_batch_task_createA

创建 Qianxin Hunter 批量查询任务,任务将以异步方式导出数据为csv。支持通过上传文件(file_path)对批量的ip/domain/company进行资产查询和结果导出,或通过搜索语法(search)进行资产查询和结果导出。成功调用后将返回 task_id,用于后续查询进度和下载文件。

ParametersJSON Schema
NameRequiredDescriptionDefault
searchNo搜索语法(与 file_path 二选一提供)。
file_pathNo包含检索目标的本地 CSV 文件路径(与 search 二选一提供)。
start_timeNo开始时间,格式为 YYYY-MM-DD(超出近30天将扣除积分)。
end_timeNo结束时间,格式为 YYYY-MM-DD(超出近30天将扣除积分)。
is_webNo资产类型,1代表”web资产“,2代表”非web资产“,3代表”全部“,默认"全部"。
status_codeNo状态码列表,以逗号分隔,如”200,401“。
fieldsNo可选返回字段,以逗号分隔(如 ip,port,domain 等)。默认为空代表选择权限内所有可导出字段。可选字段枚举: ip,port,domain,ip_tag,url,web_title,is_risk_protocol,protocol,base_protocol,status_code,os,company,number,icp_exception,country,province,city,is_web,isp,as_org,cert_sha256,ssl_certificate,component,asset_tag,updated_at,header,header_server,banner,whois,body,vul_list
search_typeNo上传文件的类型,枚举值:all、ip、domain、company,默认为all。all
assets_limitNo预期导出的资产数量。

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It correctly states the tool is asynchronous, returns a task_id, and exports CSV. However, it does not mention credit costs (hinted in parameters), destructive potential, or authorization requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and front-loaded with the main purpose. It efficiently covers multiple modes and the return value, though there is slight redundancy between the first and third sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters and an output schema, the description is adequate but could be more complete. It mentions async behavior and return of task_id but omits credit costs, prerequisites, and explicit next steps (though hinted).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description reinforces mutual exclusivity of search and file_path but adds no additional semantic meaning beyond what the parameter descriptions provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a batch query task for Qianxin Hunter, specifying asynchronous CSV export and two input modes (file upload or search syntax). This distinguishes it from sibling tools like hunter_search (single search) and the other batch task tools (progress check, download).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for batch/async queries but does not explicitly guide when to choose this tool over alternatives like hunter_search. It mentions two modes (file_path vs search) but lacks exclusions or comparative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hunter_batch_task_progressA

查看 Qianxin Hunter 批量查询任务的执行进度。

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes创建批量任务时返回的任务 ID。

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It does not disclose read-only nature, auth needs, or behavior on invalid task. Only states 'view progress' with no additional behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and resource, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one param and output schema present. Description adequately explains basic usage, though could mention polling or read-only nature for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds no extra meaning beyond schema's parameter description; it merely restates the parameter's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb ('查看/view') and resource ('Qianxin Hunter 批量查询任务的执行进度'), distinguishing it from sibling tools like hunter_batch_task_create and hunter_batch_task_result_download.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage after task creation via required task_id, but provides no explicit when-to-use or alternative guidance. Siblings are listed but not compared.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hunter_batch_task_result_downloadA

下载 Qianxin Hunter 批量查询的导出文件(CSV格式),保存到本地。注意:需先使用 hunter_batch_task_progress 确认任务已完成。

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes任务 ID。
save_dirNo可选。保存文件的目录。如果未提供,将尝试从环境变量里获取默认目录。
file_nameNo可选。保存的文件名。如果未提供,将尝试使用服务器返回的文件名。

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It mentions saving locally and CSV format but does not cover error handling, file overwrite behavior, or network retry logic. Adequate for a simple download tool but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, each delivering essential information: the primary action and the necessary prerequisite. It is front-loaded with the core function, contains no redundant words, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description need not explain return values. It covers the key aspects: action, format, save behavior, and usage context with sibling tools. Minor missing details like file size limits do not significantly detract from completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by confirming the download action and local save context, but does not provide additional constraints or meanings for parameters beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as downloading a CSV export file from Qianxin Hunter batch queries, and distinguishes it from sibling tools like hunter_batch_task_create and hunter_batch_task_progress by specifying the output format and local save behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the prerequisite of confirming task completion via hunter_batch_task_progress, providing clear when-to-use guidance. It does not, however, list alternative tools for when to not use this tool, but the context is implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.4
    • First observedhunter_batch_task_create
    • First observedhunter_batch_task_progress
    • First observedhunter_batch_task_result_download
    • First observedhunter_search

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: batch task creation, progress checking, result download, and real-time search. No overlap or ambiguity.

Naming Consistency5/5

All tools follow the 'hunter_verb_noun' pattern with snake_case, e.g., hunter_batch_task_create, hunter_search. Fully consistent.

Tool Count5/5

Four tools cover the core workflows (batch tasks lifecycle and direct search) without redundancy. Well-scoped for the server's purpose.

Completeness4/5

Covers key operations: batch task create, progress check, download, and real-time search. Minor gap in lacking a direct single-asset query, but real-time search handles it.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    An MCP server that enables AI models to query FOFA, 360 Quake, and Hunter cyberspace mapping platforms for asset discovery and security research. It supports natural language parameter configuration and provides comprehensive search tools for retrieving IP, port, and domain data.
    3
    31 PyPI
    7
    MIT
  • A
    license
    B
    quality
    B
    maintenance
    Aggregates multiple cyberspace search engines (FOFA, Quake, Hunter, ZoomEye) into a unified MCP server, enabling asset search, pagination, statistics, and account info retrieval.
    26
    MIT
  • F
    license
    A
    quality
    B
    maintenance
    An MCP server for internal data platforms that enables search, viewing, tracing, and read-only querying of business assets like dashboards, metrics, and events.
    8
    -