Kibana MCP 服务器

本项目提供了一个模型上下文协议 (MCP) 服务器的实现，允许 AI 助手与 Kibana Security 警报进行交互。

功能

此服务器向 MCP 客户端公开以下工具：

工具

• tag_alert: 向特定的 Kibana 安全警报信号添加一个或多个标签。
  • alert_id (字符串，必需): 要标记的 Kibana 警报信号的 ID。
  • tags (字符串数组，必需): 要添加到警报信号的标签列表。
• adjust_alert_status: 更改特定 Kibana 安全警报信号的状态。
  • alert_id (字符串，必需): Kibana 警报信号的 ID。
  • new_status (字符串，必需): 新状态。必须是以下之一："open"（打开）、"acknowledged"（已确认）、"closed"（已关闭）。
• get_alerts: 获取最近的 Kibana 安全警报信号，可以选择按文本过滤和限制数量。
  • limit (整数，可选，默认值: 20): 要返回的最大警报数。
  • search_text (字符串，可选): 要在警报信号字段中搜索的文本。

配置

要连接到您的 Kibana 实例，服务器需要设置以下环境变量：

• KIBANA_URL: 您的 Kibana 实例的基本 URL (例如，https://your-kibana.example.com:5601)。

以及以下一种身份验证方法：

• API 密钥 (推荐):
  • KIBANA_API_KEY: Base64 编码的 Kibana API 密钥。在 Kibana 的 Stack Management -> API Keys 下生成此密钥。确保该密钥具有读取和更新安全警报/信号的权限（例如，Security Solution 功能的适当权限）。
  • 示例格式: VzR1dU5COXdPUTRhQVZHRWw2bkk6LXFSZGRIVGNRVlN6TDA0bER4Z1JxUQ== (这只是一个示例，请使用您的实际密钥)。
• 用户名/密码 (安全性较低):
  • KIBANA_USERNAME: 您的 Kibana 用户名。
  • KIBANA_PASSWORD: 您的 Kibana 密码。

如果设置了 KIBANA_API_KEY，服务器将优先使用它。如果未设置，它将尝试使用 KIBANA_USERNAME 和 KIBANA_PASSWORD。

快速入门：运行服务器

1. 设置必需的环境变量 (KIBANA_URL 和身份验证变量)。

   • 使用 API 密钥:

     export KIBANA_URL="<your_kibana_url>"
     export KIBANA_API_KEY="<your_base64_encoded_api_key>"
     

   • 使用用户名/密码:

     export KIBANA_URL="<your_kibana_url>"
     export KIBANA_USERNAME="<your_kibana_username>"
     export KIBANA_PASSWORD="<your_kibana_password>"
     

2. 导航到项目目录 (kibana-mcp)。

3. 使用 uv 运行服务器（它使用 pyproject.toml 中定义的入口点）：

   uv run kibana-mcp
   

服务器将启动并侦听通过标准输入/输出的 MCP 连接。

连接 MCP 客户端 (例如，Cursor, Claude Desktop)

您可以配置 MCP 客户端（如 Cursor 或 Claude Desktop）以使用此服务器。

配置文件位置：

• Cursor: ~/.cursor/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%/Claude/claude_desktop_config.json (Windows)

在 mcpServers 键下添加以下服务器配置，将 /path/to/kibana-mcp 替换为您的项目根目录的实际绝对路径。 在命令参数中选择一种身份验证方法 (KIBANA_API_KEY 或 KIBANA_USERNAME/KIBANA_PASSWORD)。

推荐配置 (使用 /usr/bin/env):

某些客户端应用程序可能无法可靠地传递在其配置的 env 块中定义的环境变量。 直接使用 /usr/bin/env 可确保为服务器进程设置变量。

{
  "mcpServers": {
    "kibana-mcp": { // 您可以选择任何名称供客户端显示
      "command": "/usr/bin/env", // 使用 env 命令以提高可靠性
      "args": [
        // 在此处设置必需的环境变量
        "KIBANA_URL=<your_kibana_url>",

        // 选项 1：API 密钥 (推荐)
        "KIBANA_API_KEY=<your_base64_encoded_api_key>",

        // 选项 2：用户名/密码 (与 API 密钥互斥)
        // "KIBANA_USERNAME=<your_kibana_username>",
        // "KIBANA_PASSWORD=<your_kibana_password>",

        // 运行服务器的命令（使用绝对路径）
        "/path/to/your/virtualenv/bin/python", // 例如，/Users/me/kibana-mcp/.venv/bin/python
        "/path/to/kibana-mcp/src/kibana_mcp/server.py" // 服务器脚本的绝对路径
      ],
      "options": {
          "cwd": "/path/to/kibana-mcp" // 设置正确的工作目录
          // 使用 command/args 中的 /usr/bin/env 时，此处不需要 "env" 块
      }
    }
    // 如果需要，在此处添加其他服务器
  }
}

(注意：将占位符（如 <your_kibana_url>、<your_base64_encoded_api_key> 和 python/脚本路径）替换为您的实际值。 通常不建议将密钥直接存储在配置文件中以供生产使用。 如果需要，请考虑更安全的方式来管理环境变量。)

备用配置 (标准 env 块 - 可能无法可靠地工作):

(这是标准文档化的方法，但在某些环境中证明不可靠)

{
  "mcpServers": {
    "kibana-mcp-alt": { 
      "command": "/path/to/your/virtualenv/bin/python", 
      "args": [
        "/path/to/kibana-mcp/src/kibana_mcp/server.py"
      ],
      "options": {
          "cwd": "/path/to/kibana-mcp",
          // 选择一种身份验证方法：
          "KIBANA_API_KEY": "<your_base64_encoded_api_key>"
          // 或者
          // "KIBANA_USERNAME": "<your_kibana_username>",
          // "KIBANA_PASSWORD": "<your_kibana_password>"
      }
    }
  }
}

开发

安装依赖项

使用 uv 同步依赖项：

uv sync

构建和发布

要准备用于分发的软件包：

1. 构建软件包分发：

   uv build
   

   这将在 dist/ 目录中创建源和 wheel 分发。

2. 发布到 PyPI：

   uv publish
   

   注意：您需要配置 PyPI 凭据。

本地开发和测试环境

testing/ 目录包含使用 Docker Compose 启动本地 Elasticsearch 和 Kibana 实例的脚本和配置，并使用示例检测规则自动对其进行种子填充。

先决条件：

• Python 3
• Docker
• Docker Compose
• 用于测试脚本的 Python 依赖项：使用以下命令安装

  pip install -r requirements-dev.txt
  

快速入门：

1. 安装开发依赖项：

   pip install -r requirements-dev.txt
   

2. 从项目根目录运行快速入门脚本：

   ./testing/quickstart-test-env.sh
   

3. 该脚本 (testing/main.py) 将执行检查，启动容器，等待服务，创建示例检测规则，写入示例身份验证数据，验证信号生成，并打印访问 URL/凭据。
4. 在 http://localhost:5601 访问 Kibana (用户: elastic, 密码: elastic)。 Kibana 连接的内部用户是 kibana_system_user。

手动步骤（概述）：

testing/quickstart-test-env.sh 脚本执行 python -m testing.main。 此 Python 脚本执行以下操作：

1. 检查 Docker 和 Docker Compose。
2. 解析 testing/docker-compose.yml 以进行配置。
3. 运行 docker compose up -d。
4. 等待 Elasticsearch 和 Kibana API。
5. 为 Kibana 的内部使用创建一个自定义用户 (kibana_system_user) 和角色。
6. 创建一个索引模板 (mcp_auth_logs_template)。
7. 读取 testing/sample_rule.json（检测规则）。
8. 向 http://localhost:5601/api/detection_engine/rules 发送 POST 请求以创建规则。
9. 将来自 testing/auth_events.ndjson 的示例数据写入 mcp-auth-logs-default 索引。
10. 使用 http://localhost:5601/api/detection_engine/signals/search 检查检测信号。
11. 打印状态、URL、凭据和关闭命令。

停止测试环境：

• 运行脚本打印的关闭命令（例如，docker compose -f testing/docker-compose.yml down）。 如果需要，使用 -v 标志 (down -v) 删除数据卷。