内容
# Rapid7 InsightIDR MCP 服务器
一个用Kotlin编写的[模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，使用[MCP Kotlin SDK](https://github.com/modelcontextprotocol/kotlin-sdk)，将Rapid7 InsightIDR REST API暴露为MCP工具。
它允许具有MCP能力的助手对InsightIDR的**调查**进行分类和管理，查找**账户、资产、用户和本地账户**，处理**评论和附件**，管理**云Webhooks**和**社区威胁**，注册**收集器**，并读取**健康指标** —— 所有这些都可以通过现有的Insight平台API密钥。
> 覆盖范围基于官方API参考：
> [InsightIDR 日志搜索 REST API](https://docs.rapid7.com/insightidr/log-search-api/),
> [InsightIDR API v2 (调查)](https://help.rapid7.com/insightidr/en-us/api/v2/docs.html) 和
> [InsightIDR API v1](https://help.rapid7.com/insightidr/en-us/api/v1/docs.html).
---
## 要求
- **JDK 21+** （开发和测试针对更新的JDK；字节码针对Java 21）。
- 一个具有InsightIDR访问权限的**Insight平台API密钥** （Insight平台首页 → *API密钥*）。建议使用*组织*密钥。
- 您的Insight **区域** （您的Insight URL的前缀，例如`us`在`us.idr.insight.rapid7.com`）。
## 配置
从环境变量中读取配置：
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `INSIGHTIDR_API_KEY` | ✅ | — | Insight平台API密钥。 |
| `INSIGHTIDR_REGION` | | `us` | 区域代码：`us`, `us2`, `us3`, `eu`, `ca`, `au`, `ap`。 |
| `INSIGHTIDR_BASE_URL` | | `https://<region>.api.insight.rapid7.com` | v2 API基本URL覆盖（按v2规范服务器）。 |
| `INSIGHTIDR_V1_BASE_URL` | | `https://<region>.rest.logs.insight.rapid7.com` | v1 API基本URL覆盖（默认遵循v1规范服务器；如果租户路由v1到此处，请设置为`https://<region>.api.insight.rapid7.com`）。 |
| `INSIGHTIDR_LOG_SEARCH_BASE_URL` | | `https://<region>.rest.logs.insight.rapid7.com` | 日志搜索API基本覆盖（默认遵循日志搜索规范服务器；设置为`https://<region>.api.insight.rapid7.com/log_search`以适用于统一平台路由）。 |
| `INSIGHTIDR_TIMEOUT_MS` | | `60000` | 每个请求的超时时间（毫秒）。 |
| `INSIGHTIDR_HTTP_ALLOWED_ORIGINS` | | *（空 - 拒绝跨源）* | `--http`模式仅：通过CORS允许的逗号分隔浏览器源（例如`https://app.example.com`）。空值拒绝所有跨源浏览器访问；非浏览器MCP客户端不受影响。永远不要使用`*`。 |
参见[`.env.example`](.env.example)和[安全](#安全)。
## 构建
```PowerShell
# Windows
.\gradlew.bat shadowJar
```
```bash
# macOS / Linux
./gradlew shadowJar
```
这会在以下位置生成一个可运行的fat JAR：
```
build/libs/rapid7-insightidr-mcp-0.1.0-all.jar
```
## 运行
### 标准输入/输出（默认）
```PowerShell
# PowerShell 5.1
powershell.exe -Command { $env:INSIGHTIDR_API_KEY="xxxxx"; $env:INSIGHTIDR_REGION="us"; java -jar .\rapid7-insightidr-mcp-0.1.2-all.jar --stdio }
# PowerShell 7
pwsh.exe -Command { $env:INSIGHTIDR_API_KEY="xxxxx"; $env:INSIGHTIDR_REGION="us"; java -jar .\rapid7-insightidr-mcp-0.1.2-all.jar --stdio }
```
```bash
# macOS / Linux
INSIGHTIDR_API_KEY=xxxx INSIGHTIDR_REGION=us \
java -jar build/libs/rapid7-insightidr-mcp-0.1.2-all.jar --stdio
```
### HTTP（可流式HTTP / SSE）
默认绑定到`127.0.0.1:3001`。使用 `--host` （别名 `--ip`）覆盖监听地址，使用 `--port` 覆盖端口：
```PowerShell
# PowerShell 5.1
powershell.exe -Command { $env:INSIGHTIDR_API_KEY="xxxxx"; $env:INSIGHTIDR_REGION="us"; java -jar .\rapid7-insightidr-mcp-0.1.2-all.jar --stdio }
# PowerShell 7
pwsh.exe -Command { $env:INSIGHTIDR_API_KEY="xxxxx"; $env:INSIGHTIDR_REGION="us"; java -jar .\rapid7-insightidr-mcp-0.1.2-all.jar --stdio }
```
```bash
# macOS / Linux
INSIGHTIDR_API_KEY=xxxx INSIGHTIDR_REGION=us \
java -jar build/libs/rapid7-insightidr-mcp-0.1.2-all.jar --http --host 0.0.0.0 --port 3001
```
运行 `--help` 以查看所有选项。您也可以在开发过程中运行 `./gradlew run --args="--stdio"`。
## 与MCP客户端一起使用（例如Claude Desktop）
添加到客户端的MCP服务器配置（调整JAR路径）：
```json
{
"mcpServers": {
"insightidr": {
"command": "java",
"args": [
"-jar",
"C:\\MCP Dev\\Rapid7-InsightIDR-MCP\\build\\libs\\rapid7-insightidr-mcp-0.1.2-all.jar",
"--stdio"
],
"env": {
"INSIGHTIDR_API_KEY": "your-insight-platform-api-key",
"INSIGHTIDR_REGION": "us"
}
}
}
}
```
然后要求助手首先 `validate_connection` 以确认密钥和区域。
## 工具
### 诊断
- `validate_connection` — 通过平台 `/validate` 端点验证API密钥/区域。
### 调查（API v2 — 推荐）
- `list_investigations`, `get_investigation`, `search_investigations`
- `create_investigation`, `update_investigation`
- `set_investigation_status`, `set_investigation_priority`, `set_investigation_disposition`
- `assign_investigation`, `bulk_close_investigations`
- `list_investigation_alerts`, `get_investigation_product_alerts`, `remove_alert_from_investigation`
### 实体（API v1）
- 账户：`search_accounts`, `get_account`
- 资产：`search_assets`, `get_asset`
- 用户：`search_users`, `get_user`
- 本地账户：`search_local_accounts`, `get_local_account`
### 评论（API v1）
- `list_comments`, `get_comment`, `create_comment`, `delete_comment`, `update_comment_visibility`
### 附件（API v1）
- `list_attachments`, `get_attachment_metadata`, `download_attachment`, `delete_attachment`, `upload_attachment`
### 云Webhooks（API v1）
- `list_cloud_webhooks`, `get_cloud_webhook`, `create_cloud_webhook`, `update_cloud_webhook`, `delete_cloud_webhook`
- `test_cloud_webhook`, `replay_cloud_webhook_events`
- `add_cloud_webhook_validation`, `update_cloud_webhook_validation`, `delete_cloud_webhook_validation`
### 社区威胁（API v1）
- `create_community_threat`, `add_community_threat_indicators`, `replace_community_threat_indicators`, `delete_community_threat`
### 收集器和健康状况（API v1）
- `add_collector`
- `get_health_metrics`
### 日志搜索API (`logsearch_*`)
完整的 [日志搜索API](https://docs.rapid7.com/insightidr/log-search-api/) 覆盖，除了S3存档。默认情况下使用规范的服务器 (`https://<region>.rest.logs.insight.rapid7.com`)；参见 `INSIGHTIDR_LOG_SEARCH_BASE_URL` 以目标统一路由 (`https://<region>.api.insight.rapid7.com/log_search`)。
- **查询日志数据** （异步查询自动轮询完成；禁用时 `wait_for_completion=false`；
`per_page` 默认值为500，分页结果暴露一个 `rel: "Next"` 链接 —
将其href传递给 `logsearch_get_next_page` 以获取下一页）：
`logsearch_query_log`, `logsearch_query_logs`, `logsearch_query_logset`,
`logsearch_query_logsets_by_name`, `logsearch_poll_query`, `logsearch_get_next_page`,
`logsearch_get_context_events`, `logsearch_get_search_stats`, `logsearch_list_query_endpoints`
- **保存的查询：** `logsearch_list_saved_queries`, `logsearch_get_saved_query`,
`logsearch_create_saved_query`, `logsearch_replace_saved_query`, `logsearch_update_saved_query`,
`logsearch_delete_saved_query`, `logsearch_run_saved_query`, `logsearch_run_saved_query_on_logs`
- **日志和日志集：** `logsearch_list_logs`, `logsearch_get_log`, `logsearch_delete_log`,
`logsearch_get_log_event_sources`, `logsearch_get_log_top_keys`, `logsearch_list_logsets`,
`logsearch_get_logset`, `logsearch_replace_logset`, `logsearch_delete_logset`
- **下载和使用：** `logsearch_download_log_data`, `logsearch_get_usage_total`,
`logsearch_get_usage_per_log`, `logsearch_get_log_usage`
- **CSV导出作业：** `logsearch_list_export_jobs`, `logsearch_get_export_job`, `logsearch_delete_export_job`
- **LEQL变量：** `logsearch_list_variables`, `logsearch_get_variable`, `logsearch_create_variable`,
`logsearch_update_variable`, `logsearch_delete_variable`
- **预计算查询：** `logsearch_list_metrics`, `logsearch_get_metric`, `logsearch_query_metric`,
`logsearch_create_metric`, `logsearch_replace_metric`, `logsearch_delete_metric`
- **基本检测规则：** `logsearch_list_detection_rules`, `logsearch_get_detection_rule`,
`logsearch_create_detection_rule`, `logsearch_replace_detection_rule`, `logsearch_update_detection_rule`,
`logsearch_delete_detection_rule`，以及通知 (`logsearch_*_notification`，
`logsearch_list_notification_targets`, `logsearch_update_notification_targets`)，
目标 (`logsearch_*_target`) 和标签 (`logsearch_*_label`)
- **审计日志：** `logsearch_list_audit_logs`, `logsearch_get_audit_log`, `logsearch_audit_query_log`,
`logsearch_audit_query_logs`, `logsearch_audit_poll_query`, `logsearch_audit_list_export_jobs`,
`logsearch_audit_get_export_job`, `logsearch_audit_list_query_endpoints`
## 设计笔记
- 搜索端点 (`search_*`) 接受结构化的 `search`/`sort` 数组，直接传递给API，
匹配文档化的请求模式 (`{ field, operator, value }` / `{ field, order }`)。
- 仅读取的工具用 `readOnlyHint` 注解；删除/移除操作用破坏性注解，
以便客户端可以适当地提示。
- 结果以漂亮的JSON文本返回。非2xx响应被标记为工具错误，
并包含API的响应体，以帮助模型自我纠正。
- 日志记录到 **stderr**；**stdout** 保留用于stdio模式下的MCP JSON-RPC流。
## 许可证
参见 [LICENSE](LICENSE)。
