Elasticsearch AI

🔍 Elasticsearch MCP服务器AI

一个模型上下文协议（MCP）服务器，将Elasticsearch集群转换为AI驱动的可观察性引擎。\ 支持自然语言交互，用于分析日志、APM跟踪（使用瀑布图和RCA）和系统指标 --以最小的努力提供深入的性能和故障排除见解。

💡 Elasticsearch MCP服务器AI演示示例

• APM瀑布跟踪性能分析演示，如何使用瀑布可视化来分析应用程序跟踪，以获得深入的性能见解。快速识别真实APM数据中的瓶颈、延迟问题和服务依赖关系。

Demo APM RCA

• 演示RCA APM（根本原因分析），演示如何自动识别APM跟踪中错误和性能问题的根本原因，为快速排除故障提供可操作的见解。

Demo APM RCA

• 演示通过APM服务执行性能分析，分析和比较每个APM服务的性能指标，确定整个体系结构的延迟、吞吐量和资源瓶颈。

Demo APM RCA

🎯 核心价值：先进的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工具 ⭐ 核心价值

🔍 搜索和查询

📊 集群信息

🗂️ 索引管理

🚨 APM和监控

📝 公共参数

🔍 搜索参数

• q （query）：Elasticsearch查询字符串（例如。， "error AND @timestamp:>now-1h")
• size：结果数（默认值：10，建议最大值：100）
• 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：带标头的详细输出（true/false）
• h：要显示的特定列（例如。， "index,health,status")
• s：要排序的列（例如。， "index:desc")

🚀 安装

📦 源代码 （推荐）

选项1：简单安装（建议用户使用）

# Clone repository
git clone https://github.com/byviz/mcp-server-elasticsearch-ai.git
cd elasticsearch-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install ALL dependencies (production + development)
pip install -r requirements-all.txt

# Install package in development mode
pip install -e .

选项2：最小安装（仅运行）

# If you only want to run the server (no development)
pip install -r requirements.txt
pip install -e .

选项3：使用pyproject.toml（高级）

# Clone repository
git clone https://github.com/byviz/elasticsearch-mcp-ai.git
cd elasticsearch-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install directly from pyproject.toml
pip install -e .

📋 依赖关系文件摘要

📋 验证安装

# Verify package was installed correctly
python -c "import elasticsearch_mcp; print('✅ Installation successful')"

# Check version
python -m elasticsearch_mcp --version

⚙️ 配置

📋 所需的环境变量

弹性搜索

# Cluster connection
ELASTICSEARCH_URL="https://your-cluster.es.io:9243"

# Authentication (choose one option)
ELASTICSEARCH_USERNAME="your-username"
ELASTICSEARCH_PASSWORD="your-password"
# Or alternatively:
# ELASTICSEARCH_API_KEY="your-api-key"

🔧 可选变量

高级Elasticsearch

ELASTICSEARCH_TIMEOUT=30                     # Timeout in seconds
ELASTICSEARCH_VERIFY_CERTS=true              # Verify SSL certificates
ELASTICSEARCH_CA_CERTS="/path/to/ca.crt"     # CA certificates
ELASTICSEARCH_CLIENT_CERT="/path/to/client.crt"  # Client certificate
ELASTICSEARCH_CLIENT_KEY="/path/to/client.key"   # Private key

MCP服务器

MCP_TRANSPORT=stdio                          # Transport (stdio/http/sse)
MCP_PORT=8000                               # Port for HTTP/SSE
MCP_LOG_LEVEL=INFO                          # Logging level
MCP_ENABLE_SECURITY_FILTERING=true          # Security filtering

🚀 用法

📝 快速配置

1. 创建配置文件：

cp config.env.example .env

1. 编辑变量：

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

1. 运行服务器：

source .env
python -m elasticsearch_mcp

🎯 与Claude Desktop集成

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

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

窗户： %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分析和指标
• 集群和节点信息
• 可视化

❌ 受阻操作

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

📊 使用示例

🔍 基本搜索

"Search for documents containing 'error' in the last 30 minutes"
→ Use searchAllIndices with q="error AND @timestamp:>now-30m"

"Count how many documents are in the 'logs-2024' index"
→ Use countDocumentsInIndex with index="logs-2024"

📊 集群监控

"Is the cluster working well?"
→ Use getClusterHealth to check status (green/yellow/red)

"How many nodes does the cluster have and how much memory do they use?"
→ Use getNodeStats with metric="os,jvm" for detailed metrics

"Show basic cluster information"
→ Use getClusterInfo for name, version, and UUID

🗂️ 索引管理

"List all indices with their health status"
→ Use getCatIndices with format="json" and v=true

"What fields does the 'products' index have?"
→ Use getMapping with index="products" to see structure

"What is the configuration of the 'logs-app' index?"
→ Use getSettings with index="logs-app"

🚨 APM和故障排除

"Search for errors in the 'api-users' service from the last 2 hours"
→ Use searchAPMErrors with q="service.name:api-users AND @timestamp:>now-2h"

"What are the slowest transactions?"
→ Use searchAPMPerformance with sort="transaction.duration.us:desc"

"Analyze trace ID '430dbab7a0e0322274f076569cdc0c3d'"
→ Use analyzeTracePerformance with trace_id="430dbab7a0e0322274f076569cdc0c3d"

"Find ConnectionError patterns"
→ Use findErrorPatterns with error_type="ConnectionError"

🖥️ 系统度量

"Show CPU usage from the last 5 minutes"
→ Use searchSystemMetrics with q="metricset.name:cpu AND @timestamp:>now-5m"

"Search for ERROR level logs"
→ Use searchLogData with q="log.level:ERROR"

"Check Watcher alerts from the last 24 hours"
→ Use searchWatcherAlerts with q="@timestamp:>now-24h"

🔧 高级分析

"Find error patterns in servicio-local"
→ Use findErrorPatterns with service_name="servicio-local" and time_range="now-1h"

🛡️ 故障排除

❌ 连接错误

ERROR - Connection failed

解决方案：验证 ELASTICSEARCH_URL 以及证书

❌ 认证错误

ERROR - Authentication failed

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

❌ 证书错误

ERROR - SSL verification failed

解决方案：配置 ELASTICSEARCH_VERIFY_CERTS=false 或提供证书

📄 许可证

Apache 2.0-有关详细信息，请参阅LICENSE文件

🤝 贡献

欢迎投稿！拜托：

1. 分叉项目
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 打开拉取请求

📞 支持

需要帮助、有疑问或想建议新功能？\ 加入我们不断壮大的社区！打开一个问题或联系我们——我们在这里帮助您充分利用人工智能驱动的Elasticsearch。

伊万·弗里亚斯·莫利纳\ 弹性和Byviz

- 📧 ivan.frias@elastic.co\ - 📧 ivan.frias@byviz.com

• 领英
• 网络