麦普服务器- Elasticsearch -人工智能

Name: 麦普服务器- Elasticsearch -人工智能
Author: byviz

作者：byviz5 星标更新：2025-07-18

安装使用来源：spider==github.com

项目介绍

🔍 Elasticsearch MCP Server AI

一个基于模型上下文协议（MCP）的服务器，能够将您的Elasticsearch集群转变为一个由AI驱动的可观测性引擎。
支持通过自然语言交互分析日志、APM跟踪（包括瀑布图和根本原因分析）以及系统指标——以最小的努力提供深入的性能和故障排除洞察。

💡 示例演示 Elasticsearch MCP Server AI

示例 APM 瀑布图性能分析，如何使用瀑布可视化来分析应用程序跟踪，以获得深入的性能洞察。快速识别瓶颈、延迟问题和服务依赖关系。
示例 RCA APM（根本原因分析），演示如何自动识别APM跟踪中的错误和性能问题的根本原因，提供可操作的洞察以进行快速故障排除。
示例 APM 服务性能分析，分析并比较每个APM服务的性能指标，识别架构中的延迟、吞吐量和资源瓶颈。

🎯 核心价值：高级 APM 分析

此MCP服务器将您的Elasticsearch集群转变为强大的AI驱动的APM分析平台。关键差异化因素是我们专门的APM分析工具，这些工具提供了基本Elasticsearch查询无法实现的自动化洞察：

🔬 APM 瀑布分析 - `analyzeTracePerformance`

完整的瀑布分析APM跟踪，带有可视时间线重建
自动关联系统错误和基础设施指标
基于检测模式的性能优化建议
跨微服务和依赖关系的深度瓶颈检测
适用于：延迟调试、性能优化、依赖关系分析

🎯 APM 根本原因分析（RCA） - `findErrorPatterns`

带自动聚合和模式检测的时间错误分析
智能根本原因分析，提供具体的可操作建议
错误频率、类型和服务影响的异常检测
错误峰值与系统事件之间的自动化关联
适用于：主动故障排除、稳定性分析、事故预防

🔗 业务事件关联 - `correlateBusinessEvents`

跨所有系统接触点的完整用户旅程重建
跨索引关联（APM + 日志 + 指标 + 业务事件）
相关事件的时间轴分析及业务影响评估
从用户动作到系统响应的端到端事务跟踪
适用于：业务影响分析、关键流程调试、客户体验优化

💡 这些工具实现了使用基本Elasticsearch查询不可能实现的专用逻辑，为SRE和DevOps团队提供深入洞察和自动化分析。它们代表了此MCP服务器的核心价值主张。

🎯 这个MCP服务器是什么？

这个MCP服务器将您的Elasticsearch集群转换为强大的AI助手工具，使您能够：

🔍 智能搜索日志、指标和文档
📊 APM分析以检测错误和性能问题
🖥️ 系统监控CPU、内存和磁盘指标
🔧 应用程序问题的自动诊断

🛠️ 可用工具（25种工具）

🔧 优化的APM工具 ⭐ 核心价值

工具	描述	主要参数
`analyzeTracePerformance`	带有瀑布图和关联的完整性能分析	`trace_id`（必需），`include_errors`，`include_metrics`
`findErrorPatterns`	带有时序分析和RCA的错误模式检测	`time_range`，`service_name`，`error_type`，`min_frequency`
`correlateBusinessEvents`	业务事件关联以重建用户旅程	`correlation_id`（必需），`time_window`，`include_user_journey`

🔍 搜索和查询

工具	描述	主要参数
`searchAllIndices`	使用查询字符串在所有索引中搜索文档	`q`（查询），`size`（限制），`from`（偏移），`sort`（排序）
`searchDocuments`	在特定索引中搜索文档	`index`（索引），`q`（查询），`size`，`from`，`sort`
`countDocuments`	全局计数文档，可选过滤器	`q`（查询），`index`（特定索引）
`countDocumentsInIndex`	计算特定索引中的文档数量	`index`（必需），`q`（可选查询）
`getDocument`	通过其ID获取特定文档	`index`（必需），`id`（必需），`_source`（字段）

📊 集群信息

工具	描述	主要参数
`getClusterInfo`	基本集群信息（名称、版本、UUID）	无
`getClusterHealth`	集群健康状态及其详细指标	`level`（集群/索引/分片），`wait_for_status`，`timeout`
`getClusterStats`	完整的集群统计信息用于监控	无
`getNodeStats`	所有节点的统计信息（CPU、内存、磁盘）	`metric`（索引/操作系统/进程/JVM等）
`getHotThreads`	用于故障排除的活动线程和JVM统计信息	`metric`（JVM指标类型）

🗂️ 索引管理

工具	描述	主要参数
`getCatIndices`	带有状态信息的紧凑索引列表	`format`（json/yaml/text），`v`（详细），`h`（列），`s`（排序）
`getIndex`	特定索引的详细信息	`index`（必需）
`getMapping`	索引的字段映射和数据类型	`index`（必需）
`getSettings`	索引的配置和设置	`index`（必需）

🚨 APM 和监控

工具	描述	主要参数
`searchAPMData`	在APM数据中搜索跟踪、事务和跨度	`q`（查询），`size`，`from`，`sort`，`_source`，`timeout`
`countAPMDocuments`	计算APM索引中的文档数量（错误、跟踪、指标）	`q`（过滤查询）
`searchAPMErrors`	在APM中特别搜索错误和异常	`q`（时序查询），`size`，`from`，`sort`，`_source`，`timeout`
`searchAPMPerformance`	分析性能指标和慢事务	`q`（查询），`size`，`from`，`sort`，`_source`，`timeout`
`searchSystemMetrics`	来自Metricbeat的系统指标（CPU、内存、磁盘）	`q`（时序查询），`size`，`from`，`sort`，`_source`，`timeout`
`searchLogData`	从Filebeat和其他来源搜索应用程序日志	`q`（查询），`size`，`from`，`sort`，`_source`，`timeout`
`searchFilebeatLogs`	特别搜索来自Filebeat索引的日志	`q`（高级查询），`size`，`from`，`sort`，`_source`，`timeout`
`searchWatcherAlerts`	Elasticsearch Watcher警报历史	`q`（时序查询），`size`，`from`，`sort`，`_source`，`timeout`

📝 常见参数

🔍 搜索参数

q（查询）：Elasticsearch查询字符串（例如："error AND @timestamp:>now-1h"）
size：结果数量（默认：10，推荐最大值：110）
from：分页偏移（默认：0）
sort：排序（例如："@timestamp:desc"，"_score:desc"）
_source：要包含的具体字段（例如："@timestamp,message,service.name"）
timeout：搜索超时（默认："30s"）

📊 时序参数

time_range：时间范围（例如："now-1h"，"now-24h"，"now-7d"）
time_window：时间窗口（例如："30m"，"1h"，"5m"）
@timestamp：查询中的时序过滤器（例如："@timestamp:>now-2h"）

🏷️ 过滤参数

index：特定索引或模式（例如："logs-2024"，"logs-apm.error-*"）
service_name：APM服务名称（例如："api-users"，"servicio-local"）
error_type：错误类型（例如："ConnectionError"，"TimeoutError"）
level：详细级别（例如："cluster"，"indices"，"shards"）

🔧 格式参数

format：输出格式（例如："json"，"yaml"，"text"）
v：带有标题的详细输出（真/假）
h：要显示的具体列（例如："index,health,status"）
s：按列排序（例如："index:desc"）

🚀 安装

📦 从源代码安装（推荐）

方案1：简单安装（推荐给用户）

# 克隆仓库
git clone https://github.com/byviz/mcp-server-elasticsearch-ai.git
cd elasticsearch-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 安装所有依赖项（生产+开发）
pip install -r requirements-all.txt

# 开发模式下安装包
pip install -e .

方案2：最小安装（仅运行）

# 如果只想运行服务器（不开发）
pip install -r requirements.txt
pip install -e .

方案3：使用pyproject.toml（高级）

# 克隆仓库
git clone https://github.com/byviz/elasticsearch-mcp-ai.git
cd elasticsearch-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 直接从pyproject.toml安装
pip install -e .

📋 依赖文件总结

文件	描述	何时使用
`requirements-all.txt`	所有依赖项（生产+开发）	✅ 推荐给大多数用户
`requirements.txt`	仅最小依赖项以运行	如果需要非常轻量级的安装
`requirements-dev.txt`	仅开发依赖项	对于已经拥有基础的贡献者
`pyproject.toml`	现代Python配置	对于使用现代工具的高级用户

📋 验证安装

# 验证包是否正确安装
python -c "import elasticsearch_mcp; print('✅ 安装成功')"

# 检查版本
python -m elasticsearch_mcp --version

⚙️ 配置

📋 必需的环境变量

Elasticsearch

# 集群连接
ELASTICSEARCH_URL="https://your-cluster.es.io:9243"

# 认证（选择一种选项）
ELASTICSEARCH_USERNAME="your-username"
ELASTICSEARCH_PASSWORD="your-password"
# 或者：
# ELASTICSEARCH_API_KEY="your-api-key"

🔧 可选变量

高级Elasticsearch

ELASTICSEARCH_TIMEOUT=30                     # 超时时间（秒）
ELASTICSEARCH_VERIFY_CERTS=true              # 验证SSL证书
ELASTICSEARCH_CA_CERTS="/path/to/ca.crt"     # CA证书
ELASTICSEARCH_CLIENT_CERT="/path/to/client.crt"  # 客户端证书
ELASTICSEARCH_CLIENT_KEY="/path/to/client.key"   # 私钥

MCP服务器

MCP_TRANSPORT=stdio                          # 传输方式（stdio/http/sse）
MCP_PORT=8000                               # HTTP/SSE端口
MCP_LOG_LEVEL=INFO                          # 日志级别
MCP_ENABLE_SECURITY_FILTERING=true          # 安全过滤

🚀 使用

📝 快速配置

创建配置文件：

cp config.env.example .env

编辑变量：

# Elasticsearch
ELASTICSEARCH_URL=https://your-cluster.es.io:9243
ELASTICSEARCH_USERNAME=your-username
ELASTICSEARCH_PASSWORD=your-password

运行服务器：

source .env
python -m elasticsearch_mcp

🎯 与Claude Desktop集成

添加到您的Claude Desktop配置文件中：

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Linux: `~/.config/claude/claude_desktop_config.json`

{
  "mcpServers": {
    "elasticsearch": {
      "command": "python",
      "args": ["-m", "elasticsearch_mcp"],
      "env": {
        "ELASTICSEARCH_URL": "https://your-cluster.es.io:9243",
        "ELASTICSEARCH_USERNAME": "your-username",
        "ELASTICSEARCH_PASSWORD": "your-password"
      }
    }
  }
}

🔒 安全

默认情况下，服务器以启用安全过滤的方式运行（MCP_ENABLE_SECURITY_FILTERING=true），这会将操作限制为只读。

✅ 允许的操作

搜索和查询（GET，POST用于搜索）
读取映射、配置和统计信息
APM分析和指标
集群和节点信息
数据可视化

❌ 阻止的操作

创建、修改或删除索引
索引、更新或删除文档
修改集群配置
任何破坏性操作

📊 使用示例

🔍 基本搜索

"搜索过去30分钟内包含'error'的文档"
→ 使用searchAllIndices，q="error AND @timestamp:>now-30m"

"计算'logs-2024'索引中有多少文档"
→ 使用countDocumentsInIndex，index="logs-2024"

📊 集群监控

"集群工作正常吗？"
→ 使用getClusterHealth检查状态（绿色/黄色/红色）

"集群有多少节点，它们使用了多少内存？"
→ 使用getNodeStats，metric="os,jvm"获取详细指标

"显示基本集群信息"
→ 使用getClusterInfo获取名称、版本和UUID

🗂️ 索引管理

"列出所有索引及其健康状态"
→ 使用getCatIndices，format="json"，v=true

"'products'索引有哪些字段？"
→ 使用getMapping，index="products"查看结构

"'logs-app'索引的配置是什么？"
→ 使用getSettings，index="logs-app"

🚨 APM和故障排除

"搜索过去2小时内'api-users'服务中的错误"
→ 使用searchAPMErrors，q="service.name:api-users AND @timestamp:>now-2h"

"哪些是速度最慢的事务？"
→ 使用searchAPMPerformance，sort="transaction.duration.us:desc"

"分析跟踪ID '430dbab7a0e0322274f076569cdc0c3d'"
→ 使用analyzeTracePerformance，trace_id="430dbab7a0e0322274f076569cdc0c3d"

"查找ConnectionError模式"
→ 使用findErrorPatterns，error_type="ConnectionError"

🖥️ 系统指标

"显示过去5分钟内的CPU使用情况"
→ 使用searchSystemMetrics，q="metricset.name:cpu AND @timestamp:>now-5m"

"搜索ERROR级别的日志"
→ 使用searchLogData，q="log.level:ERROR"

"检查过去24小时内的Watcher警报"
→ 使用searchWatcherAlerts，q="@timestamp:>now-24h"

🔧 高级分析


"查找'servicio-local'中的错误模式"
→ 使用findErrorPatterns，service_name="servicio-local"，time_range="now-1h"

🛡️ 故障排除

❌ 连接错误

ERROR - 连接失败

解决方案：验证ELASTICSEARCH_URL和凭据

❌ 认证错误

ERROR - 认证失败

解决方案：验证ELASTICSEARCH_USERNAME/PASSWORD或ELASTICSEARCH_API_KEY

❌ 证书错误

ERROR - SSL验证失败

解决方案：配置ELASTICSEARCH_VERIFY_CERTS=false或

麦普服务器- Elasticsearch -人工智能

项目介绍

🔍 Elasticsearch MCP Server AI

💡 示例演示 Elasticsearch MCP Server AI

🎯 核心价值：高级 APM 分析

🔬 APM 瀑布分析 - analyzeTracePerformance

🎯 APM 根本原因分析（RCA） - findErrorPatterns

🔗 业务事件关联 - correlateBusinessEvents

🎯 这个MCP服务器是什么？

🛠️ 可用工具（25种工具）

🔧 优化的APM工具 ⭐ 核心价值

🔍 搜索和查询

📊 集群信息

🗂️ 索引管理

🚨 APM 和监控

📝 常见参数

🔍 搜索参数

📊 时序参数

🏷️ 过滤参数

🔧 格式参数

🚀 安装

📦 从源代码安装（推荐）

方案1：简单安装（推荐给用户）

方案2：最小安装（仅运行）

方案3：使用pyproject.toml（高级）

📋 依赖文件总结

📋 验证安装

⚙️ 配置

📋 必需的环境变量

Elasticsearch

🔧 可选变量

高级Elasticsearch

MCP服务器

🚀 使用

📝 快速配置

🎯 与Claude Desktop集成

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/claude/claude_desktop_config.json

🔒 安全

✅ 允许的操作

❌ 阻止的操作

📊 使用示例

🔍 基本搜索

📊 集群监控

🗂️ 索引管理

🚨 APM和故障排除

🖥️ 系统指标

🔧 高级分析

🛡️ 故障排除

❌ 连接错误

❌ 认证错误

❌ 证书错误

🔬 APM 瀑布分析 - `analyzeTracePerformance`

🎯 APM 根本原因分析（RCA） - `findErrorPatterns`

🔗 业务事件关联 - `correlateBusinessEvents`

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Linux: `~/.config/claude/claude_desktop_config.json`