Kibana MCP Server

Kibana MCP 服务

Kibana MCP 服务的实现，允许任何兼容 MCP 的客户端（例如 Claude Desktop）通过自然语言或编程请求访问你的 Kibana 实例。

本项目基于 Elastic 官方 Kibana API 文档，并使用 Elastic Stack 8.x 的 OpenAPI YAML 规范。详情请参阅 Kibana API 文档。

本项目由社区维护，并非 Elastic 或 MCP 的官方产品。

**💡 配套项目：**如需完整的 Elastic Stack 集成，可搭配 Elasticsearch MCP Server，直接执行 Elasticsearch 数据操作。

---

🚀 安装

# Global installation (recommended)
npm install -g @tocharianou/mcp-server-kibana

# Or use directly with npx
npx @tocharianou/mcp-server-kibana

从源代码安装

git clone https://github.com/TocharianOU/mcp-server-kibana.git
cd mcp-server-kibana
npm install && npm run build

---

🎯 快速开始

Claude Desktop 集成（推荐）

将以下内容添加到 Claude Desktop 配置文件：

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kibana": {
      "command": "npx",
      "args": ["@tocharianou/mcp-server-kibana"],
      "env": {
        "KIBANA_URL": "http://your-kibana-server:5601",
        "KIBANA_API_KEY": "your-api-key",
        "KIBANA_DEFAULT_SPACE": "default"
      }
    }
  }
}

直接使用 CLI

# Using API Key (recommended)
KIBANA_URL=http://localhost:5601 \
KIBANA_API_KEY=your-api-key \
npx @tocharianou/mcp-server-kibana

# Using Basic Auth
KIBANA_URL=http://localhost:5601 \
KIBANA_USERNAME=your-username \
KIBANA_PASSWORD=your-password \
npx @tocharianou/mcp-server-kibana

# Using Cookie Auth
KIBANA_URL=http://localhost:5601 \
KIBANA_COOKIES="sid=xxx; security-session=yyy" \
npx @tocharianou/mcp-server-kibana

HTTP 模式（远程访问）

MCP_TRANSPORT=http \
MCP_HTTP_PORT=3000 \
KIBANA_URL=http://localhost:5601 \
KIBANA_API_KEY=your-api-key \
npx @tocharianou/mcp-server-kibana

访问地址：http://localhost:3000/mcp
健康检查：http://localhost:3000/health

保护 HTTP 模式。/mcp 上的每个会话都会使用启动服务时配置的 Kibana 凭据，因此请将此端点视为敏感端点：

• 默认情况下，服务仅监听 localhost，并拒绝 Host 标头不是环回地址名称的请求（防止 DNS 重绑定）。
• 若要接受远程客户端，请设置 MCP_BEARER_TOKEN。客户端必须在每个 /mcp 请求中发送 Authorization: Bearer <token>。/health 仍保持开放。
• 如果绑定到非环回地址（MCP_HTTP_HOST=0.0.0.0）时未设置 MCP_BEARER_TOKEN，启动时会记录警告：任何能够访问该端口的人都可以使用你的 Kibana 凭据。
• 如果反向代理会将公开的 Host 标头转发到绑定到 localhost 的服务，请将该主机名添加到 MCP_ALLOWED_HOSTS。

MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
KIBANA_URL=http://localhost:5601 \
KIBANA_API_KEY=your-api-key \
npx @tocharianou/mcp-server-kibana

---

✨ 功能

核心能力

• 双传输模式：Stdio（本地）和 HTTP（远程访问）
• 多种身份验证方式：API Key、Basic Auth、基于 Cookie 的身份验证
• 多空间支持：适用于企业的 Kibana 空间管理
• SSL/TLS 支持：自定义 CA 证书配置
• 会话管理：为 HTTP 模式自动生成 UUID
• 动态 API 发现：基于官方 Kibana OpenAPI 规范

已保存对象管理

• 对所有 Kibana 已保存对象类型执行完整的 CRUD 操作
• 支持分页的智能搜索
• 高效批量更新的批量操作
• 支持乐观并发控制的版本控制
• 对象关系的引用管理

---

🔧 配置

必需变量

变量	说明	示例
KIBANA_URL	Kibana 服务地址	http://localhost:5601

身份验证（选择一种方式）

变量	说明	优先级
KIBANA_API_KEY	API Key（Base64 编码）	第 1 优先级
KIBANA_USERNAME + KIBANA_PASSWORD	Basic 身份验证	第 2 优先级
KIBANA_COOKIES	会话 Cookie	第 3 优先级

可选变量

变量	描述	默认值
KIBANA_DEFAULT_SPACE	默认 Kibana 空间	default
KIBANA_CA_CERT	CA 证书路径	-
KIBANA_TIMEOUT	请求超时（ms）	60000
MCP_TRANSPORT	传输模式	stdio
MCP_HTTP_PORT	HTTP 服务端口	3000
MCP_HTTP_HOST	HTTP 服务主机	localhost
MCP_BEARER_TOKEN	HTTP 模式：在 /mcp 上要求提供 Authorization: Bearer <token>	-
MCP_ALLOWED_HOSTS	HTTP 模式：Host 标头中接受的额外主机名（逗号分隔）	-
NODE_TLS_REJECT_UNAUTHORIZED	禁用 SSL 验证	1

---

🛠️ 可用工具

基础工具

• get_status - 获取 Kibana 服务状态
• execute_kb_api - 执行自定义 Kibana API 请求
• search_elasticsearch - 通过 Kibana 的搜索 API 搜索 Elasticsearch 文档和日志，受限于用户的 Elasticsearch 索引权限
• get_available_spaces - 列出可用的 Kibana 空间
• search_kibana_api_paths - 搜索 API 端点
• list_all_kibana_api_paths - 列出所有 API 端点
• get_kibana_api_detail - 获取 API 端点详情

已保存对象工具

• vl_search_saved_objects - 搜索已保存对象（通用）
• vl_get_saved_object - 获取单个已保存对象
• vl_create_saved_object - 创建新的已保存对象
• vl_update_saved_object - 更新单个已保存对象
• vl_bulk_update_saved_objects - 批量更新操作
• vl_bulk_delete_saved_objects - 批量删除操作

支持的对象类型： dashboard、visualization、index-pattern、search、config、lens、map、tag、canvas-workpad、canvas-element

分析工具（v0.6.0+）

• analyze_object_dependencies - 分析已保存对象的依赖关系
• analyze_deletion_impact - 检查删除前的影响
• check_dashboard_health - 检查仪表板健康状况
• scan_all_dashboards_health - 批量扫描仪表板健康状况

Elasticsearch 数据搜索

需要在 Elasticsearch 中搜索文档、应用程序日志、追踪记录或聚合数据时，请使用 search_elasticsearch。它通过 Kibana 的 /internal/search/es 路由发送 Query DSL，而不是使用 Dev Tools Console 代理。

该工具为只读工具，不会扩大数据访问权限：Elasticsearch 会在每次搜索时强制执行所配置用户的索引权限，与 Discover 和仪表板的执行方式完全一致。用户无权读取的索引不会返回任何结果。

提供此工具的原因是，Dev Tools Console 代理（/api/console/proxy）受独立的 Kibana 权限控制，因为 Console 可以调用任何 Elasticsearch API，包括写入和管理端点。能够读取目标索引但没有 Dev Tools 权限的用户，通过 Console 代理会收到 403；此工具可让该用户执行搜索，仅此而已。如果你的 Kibana 管理员依靠不授予 Dev Tools 权限来阻止某个账户执行临时查询，请注意，此工具允许该账户使用 Query DSL 搜索。

有界日志搜索的工具参数示例：

{
  "index": "application-logs-*",
  "body": {
    "size": 20,
    "_source": [
      "@timestamp",
      "message",
      "trace.id",
      "service.name"
    ],
    "sort": [
      { "@timestamp": "desc" }
    ],
    "query": {
      "bool": {
        "filter": [
          {
            "range": {
              "@timestamp": {
                "gte": "2025-01-15T10:00:00Z",
                "lt": "2025-01-15T11:00:00Z"
              }
            }
          },
          {
            "term": {
              "service.name.keyword": "example-service"
            }
          }
        ]
      }
    }
  }
}

对于大量日志，请先使用较小的时间范围和较小的 size。找到追踪 ID 或关联 ID 后，在第二次精确搜索中使用该值，而不要反复扫描较大的时间范围。使用 _source 仅保留当前调查所需的字段。

该工具会拒绝仅包含通配符的索引片段，例如 *、** 或 _all（包括逗号分隔的索引表达式中的此类片段）、空搜索主体，以及大于 100 的 body.size。字符串类型的 size 值会被转换并作为数字进行验证。该端点是 Kibana 内部 API，因此应在 Kibana 主要版本升级后验证其兼容性。

---

📖 资源

资源 URI	描述
kibana-api://paths	列出所有可用的 API 端点
kibana-api://paths?search=<keyword>	按关键字搜索端点
kibana-api://path/{method}/{encoded_path}	获取指定端点的详情

---

💬 示例查询

基本操作

• “我的 Kibana 服务状态如何？”
• “列出所有可用的 Kibana 空间”
• “显示所有与仪表板相关的 API 端点”

Elasticsearch 和日志

• “搜索过去一小时内服务 X 的生产日志，查找错误”
• “查找此跟踪 ID，并按时间顺序显示前后相关的日志事件”
• “使用此 Elasticsearch Query DSL 搜索索引 application-logs-*”
• “按服务统计此时间范围内的错误数量”

已保存的对象

• “搜索所有仪表板”
• “查找标题中包含‘nginx’的可视化”
• “创建名为‘Sales Overview’的新仪表板”
• “更新仪表板‘my-dashboard-123’的描述”
• “按 ID 删除多个仪表板”

健康状况和分析

• “检查仪表板‘overview’的健康状况”
• “分析可视化‘viz-123’的依赖项”
• “扫描所有仪表板，查找健康问题”

---

🐛 故障排除

连接问题

• 确认 Kibana URL 可以访问
• 检查身份验证凭据
• 对于 SSL 问题：NODE_TLS_REJECT_UNAUTHORIZED=0（请谨慎使用）

Claude Desktop 问题

• 更改配置后重启 Claude Desktop
• 验证 JSON 配置语法
• 检查控制台日志中的错误

常见错误

• “import: command not found”：更新到最新版本
• 身份验证失败：验证凭据和权限
• SSL 错误：检查 CA 证书或禁用 SSL 验证
• 搜索 Elasticsearch 时 /api/console/proxy 返回 403：使用 search_elasticsearch。即使用户有权限读取目标索引，Console 代理仍可能要求具备 Kibana Dev Tools 权限。

---

🔍 调试

使用 MCP Inspector 进行调试：

npm run inspector

这会提供一个可通过浏览器访问的调试界面。

---

📦 软件包信息

• NPM： @tocharianou/mcp-server-kibana
• GitHub：TocharianOU/mcp-server-kibana
• Node.js：>= 18.0.0
• 许可证：Apache 2.0

---

🤝 参与贡献

此项目由社区维护。欢迎贡献和反馈！

请在所有交流中遵守 Elastic 社区行为准则。

---

📄 许可证

Apache License 2.0 - 详情请参阅 LICENSE 文件。