内容
<p align="center">
<img src="docs/assets/thehive-mcp-banner.jpg" alt="thehive-mcp banner" width="100%" />
</p>
<h1 align="center">thehive-mcp</h1>
<p align="center">
<strong>一个给予AI客户端对TheHive完全读写控制的MCP服务器，适用于案例、警报、任务、可观察性和Cortex分析器，通过stdio进行通信，默认情况下破坏性操作是关闭的。</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/thehive-mcp"><img src="https://img.shields.io/npm/v/thehive-mcp?style=for-the-badge&logo=npm&color=cb3837&label=npm" alt="npm version" /></a>
<a href="https://github.com/lidless-labs/thehive-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/thehive-mcp/ci.yml?branch=main&style=for-the-badge&label=CI&logo=github" alt="CI status" /></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-server-6f42c1?style=for-the-badge" alt="MCP server" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT license" /></a>
</p>
<p align="center">
<strong>官网： <a href="https://lidless.dev/thehive-mcp">lidless.dev/thehive-mcp</a></strong>
</p>
thehive-mcp 是一个适用于 [TheHive](https://thehive-project.org/) 的模型上下文协议（MCP）服务器，这是一个开源的安全事件响应平台。它允许AI客户端通过一个stdio进程运行SOC工作流：打开和分类案例、提升警报、跟踪可观察性、驱动任务和运行Cortex分析器。它的特点是安全性，破坏性操作（删除、合并、提升、原始查询）默认情况下是关闭的，只有在显式环境标志打开时才可用。
## 它做什么
thehive-mcp 是适用于 **TheHive** 事件响应和案例管理的MCP服务器。它公开了47种模型上下文协议工具，映射到TheHive 5 API的全部表面，因此MCP客户端（Claude Desktop、Claude Code、Codex CLI、OpenClaw、Hermes等）可以驱动安全运营中心：创建和分类案例、管理警报、添加和搜索可观察性、运行和轮询Cortex分析器、记录任务日志和评论，并编排SOAR风格的事件响应工作流，使用自然语言。它通过TheHive实例的REST API进行通信，通过stdio进行MCP通信，因此它可以与任何支持该协议的代理程序一起使用，而无需运行额外的服务。
与其他MCP服务器不同，它具有安全性。不可逆操作（`thehive_delete_case`、`thehive_delete_alert`、`thehive_merge_cases`、`thehive_promote_alert`）和原始查询DSL工具默认情况下是关闭的，只有在显式环境标志打开时才可用。TLS放松仅适用于TheHive请求，不适用于整个过程。该服务器针对运行中的 **TheHive 5.4.11** 实例进行了测试，涵盖读取、写入和破坏性工作流。
## 快速开始
直接从npm运行，无需全局安装：
```bash
npx -y thehive-mcp
```
使用两个环境变量指向TheHive实例：
```bash
THEHIVE_URL=https://192.0.2.10:9000 \
THEHIVE_API_KEY=your-api-key \
npx -y thehive-mcp
```
服务器通过stdio进行MCP通信，因此它旨在由MCP客户端启动，而不是手动运行。下面的客户端配置是正常的入口点。
### MCP客户端配置
将以下内容放入任何读取标准`mcpServers`映射的MCP客户端（Claude Desktop、Claude Code和大多数其他客户端使用此确切形状）：
```json
{
"mcpServers": {
"thehive": {
"command": "npx",
"args": ["-y", "thehive-mcp"],
"env": {
"THEHIVE_URL": "https://192.0.2.10:9000",
"THEHIVE_API_KEY": "your-api-key"
}
}
}
}
```
要启用受限破坏性工具和原始查询DSL工具，请将它们添加到`env`：
```json
{
"mcpServers": {
"thehive": {
"command": "npx",
"args": ["-y", "thehive-mcp"],
"env": {
"THEHIVE_URL": "https://192.0.2.10:9000",
"THEHIVE_API_KEY": "your-api-key",
"THEHIVE_ALLOW_DESTRUCTIVE_TOOLS": "true",
"THEHIVE_ENABLE_RAW_QUERY": "true"
}
}
}
}
```
对于Claude Desktop，配置文件位于 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）。每个工具的说明（Claude Code、Codex CLI、OpenClaw、Hermes）都在下面的 [客户端设置](#客户端设置) 中。
## 配置
设置环境变量：
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `THEHIVE_URL` | 是 | - | TheHive实例URL，使用`http`或`https`（例如`https://192.0.2.10:9000`） |
| `THEHIVE_API_KEY` | 是 | - | 身份验证的API密钥 |
| `THEHIVE_VERIFY_SSL` | 否 | `true` | 仅在自签名TLS的受信任实验室系统上设置为`false`。禁用时，TLS验证仅针对TheHive请求放松（通过作用域调度器），不适用于整个过程 |
| `THEHIVE_TIMEOUT` | 否 | `30` | 请求超时（1-300）秒 |
| `THEHIVE_ALLOW_DESTRUCTIVE_TOOLS` | 否 | `false` | 设置为`true`以启用破坏性/不可逆MCP工具（`thehive_delete_case`、`thehive_delete_alert`、`thehive_merge_cases`、`thehive_promote_alert`） |
| `THEHIVE_ENABLE_RAW_QUERY` | 否 | `false` | 设置为`true`以启用原始查询DSL MCP工具 |
## 工具
47种工具，涵盖案例、警报、任务、可观察性、Cortex等。四个破坏性工具和原始查询工具通过环境标志控制，如下所示。
### 案例（16种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_cases` | 列出案例，带有过滤器（状态、严重程度、标签、所有者） |
| `thehive_get_case` | 获取特定案例的ID |
| `thehive_create_case` | 创建新案例 |
| `thehive_update_case` | 更新案例字段（严重程度、状态、标签等） |
| `thehive_search_cases` | 按标题关键词搜索案例 |
| `thehive_close_case` | 关闭案例，带有解决方案状态和摘要 |
| `thehive_assign_case` | 将案例分配给用户 |
| `thehive_update_case_custom_fields` | 更新案例自定义字段 |
| `thehive_add_case_tags` | 添加标签而不替换现有标签 |
| `thehive_remove_case_tags` | 删除选定的标签 |
| `thehive_set_case_flag` | 设置或清除案例标志 |
| `thehive_bulk_assign_cases` | 将多个案例分配给用户 |
| `thehive_bulk_close_cases` | 关闭多个案例，带有相同的解决方案 |
| `thehive_case_timeline_summary` | 总结案例详情、任务、可观察性和评论 |
| `thehive_delete_case` | 永久删除案例（可选强制）。需要 `THEHIVE_ALLOW_DESTRUCTIVE_TOOLS=true` |
| `thehive_merge_cases` | 合并多个案例为一个（不可逆）。需要 `THEHIVE_ALLOW_DESTRUCTIVE_TOOLS=true` |
### 警报（6种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_alerts` | 列出警报，带有过滤器（状态、严重程度、来源、类型） |
| `thehive_get_alert` | 获取特定警报的ID |
| `thehive_create_alert` | 创建新警报 |
| `thehive_update_alert` | 更新警报字段 |
| `thehive_promote_alert` | 将警报提升为案例（创建新案例）。需要 `THEHIVE_ALLOW_DESTRUCTIVE_TOOLS=true` |
| `thehive_delete_alert` | 永久删除警报。需要 `THEHIVE_ALLOW_DESTRUCTIVE_TOOLS=true` |
### 任务（4种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_tasks` | 列出案例的任务 |
| `thehive_get_task` | 获取特定任务的ID |
| `thehive_create_task` | 在案例中创建任务 |
| `thehive_update_task` | 更新任务字段（状态、分配者等） |
### 可观察性（5种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_observables` | 列出案例的可观察性 |
| `thehive_get_observable` | 获取特定可观察性的ID |
| `thehive_create_observable` | 向案例添加单个可观察性 |
| `thehive_create_observable_bulk` | 在一个请求中添加多个相同类型可观察性 |
| `thehive_search_observables` | 跨所有案例搜索可观察性 |
### 任务日志（2种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_task_logs` | 列出任务的日志条目 |
| `thehive_create_task_log` | 向任务添加日志条目 |
### 评论（2种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_comments` | 列出案例的评论 |
| `thehive_create_comment` | 向案例添加评论 |
### 用户（2种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_users` | 列出组织中的用户 |
| `thehive_get_current_user` | 获取已认证用户的配置文件 |
### Cortex（7种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_analyzers` | 列出可用的Cortex分析器 |
| `thehive_get_observable_enrichment_options` | 列出可丰富可观察性的分析器 |
| `thehive_run_analyzer` | 在可观察性上运行Cortex分析器 |
| `thehive_run_analyzer_and_wait` | 运行分析器并等待完成 |
| `thehive_get_job` | 获取分析器作业状态和结果 |
| `thehive_wait_for_job` | 轮询作业直到达到终端状态 |
| `thehive_summarize_job_report` | 返回紧凑的分析器报告摘要 |
### 查询（1种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_query` | 在启用 `THEHIVE_ENABLE_RAW_QUERY=true` 时执行受保护的原始TheHive查询DSL进行复杂搜索 |
### 模板（1种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_list_case_templates` | 列出可用的案例模板 |
### 状态（1种工具）
| 工具 | 描述 |
| --- | --- |
| `thehive_status` | 获取服务器健康状况、版本和功能 |
## 提示模板
| 提示 | 描述 |
| --- | --- |
| `case-summary` | 生成综合事件案例报告 |
| `alert-triage` | 对警报进行分类和分析以进行升级 |
| `incident-response` | 有导向的事件响应工作流 |
## 资源
| 资源 | URI | 描述 |
| --- | --- | --- |
| 打开案例 | `thehive://cases/open` | 当前打开的案例 |
| 新警报 | `thehive://alerts/new` | 未处理的警报 |
| 当前用户 | `thehive://user/current` | 已认证的用户信息 |
## 客户端设置
上述 [MCP客户端配置](#mcp客户端配置) 适用于任何读取标准 `mcpServers` 映射的客户端。下面的说明涵盖了具有自己设置命令的客户端以及每个客户端的源码变体。
### Claude Code
```bash
claude mcp add thehive \
--env THEHIVE_URL=https://192.0.2.10:9000 \
--env THEHIVE_API_KEY=your-api-key \
-- npx -y thehive-mcp
```
添加 `--scope user` 以使其在任何目录中可用，而不仅仅是当前项目。
### Codex CLI
[Codex CLI](https://github.com/openai/codex) 通过 `codex mcp add` 注册MCP服务器：
```bash
codex mcp add thehive \
--env THEHIVE_URL=https://192.0.2.10:9000 \
--env THEHIVE_API_KEY=your-api-key \
-- npx -y thehive-mcp
```
Codex 将条目写入 `~/.codex/config.toml` 下的 `[mcp_servers.thehive]`。通过 `codex mcp list` 验证。
### OpenClaw
```bash
openclaw mcp set thehive '{
"command": "npx",
"args": ["-y", "thehive-mcp"],
"env": {
"THEHIVE_URL": "https://192.0.2.10:9000",
"THEHIVE_API_KEY": "your-api-key"
}
}'
```
然后重启网关并确认注册：
```bash
systemctl --user restart openclaw-gateway
openclaw mcp list
```
### Hermes Agent
[Hermes Agent](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 读取MCP配置，在 `mcp_servers` 键下：
```yaml
mcp_servers:
thehive:
command: "npx"
args: ["-y", "thehive-mcp"]
env:
THEHIVE_URL: "https://192.0.2.10:9000"
THEHIVE_API_KEY: "your-api-key"
```
然后在Hermes会话内使用 `/reload-mcp` 重新加载MCP。
### 源码变体
如果您从源码构建而不是npm包，请将 `command`/`args` 指向构建的 `dist/index.js`:
```json
{
"command": "node",
"args": ["/absolute/path/to/thehive-mcp/dist/index.js"]
}
```
## 为什么不直接使用TheHive REST API？
您可以，但对于脚本您应该使用。REST API是合适的工具，当您已经知道确切的端点时。thehive-mcp 存在于AI代理进行决策的情况：它将API转换为47个命名、类型化、描述的工具，MCP客户端可以选择自然语言，处理TheHive 5的怪癖（204 PATCH响应、数组形状的可观察性创建、连接器端点 `/api/connector/`）、并在不可逆的动词前面添加安全防护措施，以便模型无法删除或合并案例数据，除非您明确选择启用。原始HTTP客户端不提供这些功能。
## 为什么不使用通用OpenAPI到MCP桥接器？
通用桥接器公开每个端点扁平，没有危险性概念，也没有TheHive 5的行为边缘。thehive-mcp 是为TheHive手工构建的：破坏性工具被控制，原始查询DSL被控制和形状检查，TLS放松仅适用于TheHive请求，敏感值从错误输出中删除，并且工具描述携带正确的TheHive 5状态枚举（TruePositive、FalsePositive等，而不是旧的“Resolved”）。这些是通用桥接器无法为您做出的决定。
## whathive-mcp 不是
- 它不是TheHive的替代品。您需要一个运行中的TheHive 5实例和有效的API密钥；此服务器仅与之一起工作。
- 它不是托管服务或守护进程。它是一个stdio进程，您的MCP客户端按需启动。没有任何端口监听器，也没有任何电话回家。
- 它不是Cortex服务器。它通过TheHive的连接器驱动Cortex分析器，但分析器执行发生在您自己的Cortex部署中。对于专用的Cortex MCP服务器，请参阅 [cortex-mcp](https://lidless.dev/cortex-mcp)。
- 它不是通过省略安全功能安全。
## 开发
```bash
# 安装依赖
npm install
# 构建
npm run build
# 运行测试
npm test
# 运行仅读的实时集成测试（跳过环境变量缺失时）
THEHIVE_URL=https://192.0.2.10:9000 THEHIVE_API_KEY=your-key npx tsx scripts/live-test.ts
# 运行写操作的实时测试
THEHIVE_URL=https://192.0.2.10:9000 THEHIVE_API_KEY=your-key THEHIVE_LIVE_ALLOW_WRITES=true npx tsx scripts/live-test.ts
# 运行包含破坏性清理、删除和合并检查的写操作实时测试
THEHIVE_URL=https://192.0.2.10:9000 THEHIVE_API_KEY=your-key THEHIVE_LIVE_ALLOW_WRITES=true THEHIVE_LIVE_ALLOW_DESTRUCTIVE=true npx tsx scripts/live-test.ts
# 类型检查
npm run typecheck
# 开发模式
THEHIVE_URL=https://192.0.2.10:9000 THEHIVE_API_KEY=your-key npm run dev
```
## 贡献
欢迎提交错误报告和补丁。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解容易实施的内容， [SECURITY.md](SECURITY.md) 报告漏洞， 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。问题模板位于 [.github/ISSUE_TEMPLATE](.github/ISSUE_TEMPLATE)。
## 许可
[MIT](LICENSE)
