Elasticsearch MCP Server - 企业级搜索引擎的智能桥梁

Posted on 十月 11, 2025

Elasticsearch MCP Server - 企业级搜索引擎的智能桥梁

官方实现 | Stars: 512 | Rust | Elastic License 2.0 | 实验性

概述

Elasticsearch MCP Server 是 Elastic 官方提供的 Model Context Protocol 实现，为 AI Agent 提供了与 Elasticsearch 数据的自然语言交互能力。通过这个 MCP 服务器，AI 助手可以直接探索、查询和分析 Elasticsearch 索引中的数据，无需编写复杂的查询语句。

该服务器使用 Rust 编写，提供了高性能、内存安全的实现。它支持多种连接协议（stdio、SSE、streamable-HTTP），能够无缝集成到各种 MCP 客户端中。作为实验性项目，它正在持续演进，为企业级搜索应用与 AI 的结合开辟了新的可能性。

核心特性

✅ Elastic 官方实现，与 Elasticsearch 深度集成
🛠️ 5 个核心工具：索引管理、映射查询、搜索、ES|QL、分片信息
🚀 高性能 Rust 实现（93.8%），内存安全
🎯 支持多种查询方式：Query DSL、ES|QL
🌐 多协议支持：stdio、SSE、streamable-HTTP
🔐 灵活的认证方式：API Key、用户名密码
📊 支持 Elasticsearch 8.x 和 9.x
🐳 Docker 官方镜像，开箱即用

工具列表

1. list_indices

功能：列出所有可用的 Elasticsearch 索引及其健康状态

参数：无

返回信息：

索引名称
健康状态（green、yellow、red）
文档数量
存储大小

使用场景：

探索 Elasticsearch 集群中的数据结构
检查索引健康状态
发现可用的数据源

示例：

1
2
3

{
  "tool": "list_indices"
}

2. get_mappings

功能：获取指定 Elasticsearch 索引的字段映射信息

参数：

index (string, 必需) - 索引名称

返回信息：

字段名称和类型
字段属性（analyzed、indexed 等）
嵌套对象结构

使用场景：

了解索引的数据结构
确定可查询的字段
设计查询语句前的准备

示例：

{
  "tool": "get_mappings",
  "arguments": {
    "index": "products"
  }
}

3. search

功能：使用 Query DSL 执行 Elasticsearch 搜索查询

参数：

index (string, 必需) - 要搜索的索引名称
query (object, 必需) - Query DSL 查询对象
size (number, 可选) - 返回结果数量（默认 10）

查询类型支持：

Match 查询：全文搜索
Term 查询：精确匹配
Range 查询：范围查询
Bool 查询：组合查询
Aggregations：聚合分析

示例 1：全文搜索

{
  "tool": "search",
  "arguments": {
    "index": "products",
    "query": {
      "match": {
        "description": "laptop"
      }
    },
    "size": 20
  }
}

示例 2：组合查询

{
  "tool": "search",
  "arguments": {
    "index": "logs",
    "query": {
      "bool": {
        "must": [
          {"match": {"level": "ERROR"}},
          {"range": {"timestamp": {"gte": "2025-10-01"}}}
        ]
      }
    }
  }
}

4. esql

功能：执行 ES|QL 查询（Elasticsearch 查询语言）

参数：

query (string, 必需) - ES|QL 查询语句

ES|QL 特性：

SQL 风格的查询语法
支持 JOIN、聚合、过滤
更直观的数据分析方式

使用场景：

复杂数据分析
报表生成
数据探索

示例 1：基础查询

FROM logs
| WHERE level == "ERROR"
| STATS count = COUNT(*) BY service
| SORT count DESC
| LIMIT 10

示例 2：聚合分析

FROM sales
| WHERE date >= "2025-01-01"
| STATS total_revenue = SUM(amount), avg_price = AVG(amount) BY product_category
| SORT total_revenue DESC

5. get_shards

功能：获取索引的分片详细信息

参数：

index (string, 可选) - 索引名称（不指定则返回所有索引）

返回信息：

分片 ID
分片状态（STARTED、INITIALIZING、RELOCATING）
主分片/副本分片
节点信息
文档数量
存储大小

使用场景：

集群健康诊断
性能优化
容量规划

示例：

{
  "tool": "get_shards",
  "arguments": {
    "index": "products"
  }
}

配置方式

环境变量

# Elasticsearch 集群 URL（必需）
ES_URL=https://your-cluster.es.cloud:9243

# 认证方式 1：API Key（推荐）
ES_API_KEY=your-api-key-here

# 认证方式 2：用户名密码
ES_USERNAME=elastic
ES_PASSWORD=your-password

# 可选：跳过 SSL 证书验证（仅用于开发环境）
ES_SSL_SKIP_VERIFY=false

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch",
        "stdio"
      ],
      "env": {
        "ES_URL": "https://your-cluster.es.cloud:9243",
        "ES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Docker 部署

1. Stdio 协议（Claude Desktop）

docker run -i --rm \
  -e ES_URL="https://your-cluster.es.cloud:9243" \
  -e ES_API_KEY="your-api-key" \
  docker.elastic.co/mcp/elasticsearch stdio

2. Streamable-HTTP（推荐用于 Web 应用）

docker run --rm \
  -e ES_URL="https://your-cluster.es.cloud:9243" \
  -e ES_API_KEY="your-api-key" \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch http

3. SSE 协议

docker run --rm \
  -e ES_URL="https://your-cluster.es.cloud:9243" \
  -e ES_API_KEY="your-api-key" \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch sse

使用用户名密码认证

docker run -i --rm \
  -e ES_URL="https://your-cluster.es.cloud:9243" \
  -e ES_USERNAME="elastic" \
  -e ES_PASSWORD="your-password" \
  docker.elastic.co/mcp/elasticsearch stdio

使用场景

1. 日志分析与故障排查

通过自然语言查询日志数据，快速定位问题。

示例流程：

AI 询问：”过去 24 小时有哪些错误？”
MCP 服务器执行 ES|QL 查询
返回错误日志统计和详情
AI 进一步分析根因

Query DSL 示例：

{
  "query": {
    "bool": {
      "must": [
        {"match": {"level": "ERROR"}},
        {"range": {"timestamp": {"gte": "now-24h"}}}
      ]
    }
  },
  "sort": [{"timestamp": "desc"}]
}

2. 电商产品搜索

为电商应用提供智能产品推荐和搜索功能。

示例流程：

用户询问：”推荐价格在 500-1000 元的笔记本电脑”
AI 转换为 Elasticsearch 查询
返回符合条件的产品列表
根据销量、评分排序

Query 示例：

{
  "query": {
    "bool": {
      "must": [
        {"match": {"category": "laptop"}},
        {"range": {"price": {"gte": 500, "lte": 1000}}}
      ]
    }
  },
  "sort": [
    {"sales_count": "desc"},
    {"rating": "desc"}
  ]
}

3. 实时数据监控

监控系统指标和业务数据，实时发现异常。

示例流程：

AI 定期查询最新指标数据
检测异常趋势
发送警报通知
提供优化建议

ES|QL 示例：

FROM metrics
| WHERE timestamp >= NOW() - 1 HOUR
| STATS avg_cpu = AVG(cpu_usage), max_memory = MAX(memory_usage) BY host
| WHERE avg_cpu > 80 OR max_memory > 90

4. 企业搜索应用

构建智能企业知识库，支持自然语言检索。

示例流程：

员工询问：”公司的休假政策是什么？”
搜索文档索引
返回相关政策文档
AI 总结关键信息

5. 数据分析与报表

通过 AI 辅助进行数据分析和报表生成。

示例流程：

业务人员询问：”上个月销售额最高的产品类别是什么？”
执行聚合查询
生成可视化数据
提供业务洞察

技术架构

系统组件

┌─────────────────┐
│  MCP Client     │
│ (Claude Desktop)│
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│ Elasticsearch   │
│  MCP Server     │
│    (Rust)       │
└────────┬────────┘
         │ Elasticsearch Client
         ▼
┌─────────────────┐
│ Elasticsearch   │
│    Cluster      │
└─────────────────┘

数据流程

用户自然语言查询
    ↓
MCP 客户端（Claude）
    ↓
MCP 协议传输
    ↓
Elasticsearch MCP Server
    ↓
转换为 Query DSL/ES|QL
    ↓
Elasticsearch 集群
    ↓
返回搜索结果
    ↓
AI 处理和呈现

支持的协议

协议	适用场景	优势
stdio	Claude Desktop、命令行工具	简单、低延迟
SSE	Web 应用、浏览器客户端	实时推送、单向流
streamable-HTTP	Web 应用、微服务	双向流、更灵活

与其他搜索方案对比

特性	Elasticsearch MCP	Meilisearch MCP	MongoDB MCP
搜索类型	全文搜索、分析	快速搜索	文档查询
查询语言	Query DSL + ES	QL	简单过滤
分析能力	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
性能	高（大数据）	极快（小数据）	中
扩展性	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
适用场景	企业搜索、日志分析	网站搜索	通用数据库

最佳实践

1. 选择合适的认证方式

# 生产环境推荐：API Key
ES_API_KEY=$(curl -X POST "https://your-cluster.es.cloud:9243/_security/api_key" \
  -u elastic:password \
  -H "Content-Type: application/json" \
  -d '{"name":"mcp-server","expiration":"30d"}' | jq -r '.encoded')

# 开发环境：用户名密码
ES_USERNAME=elastic
ES_PASSWORD=changeme

2. 优化查询性能

使用过滤器而非查询：

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"status": "active"}},
        {"range": {"date": {"gte": "2025-01-01"}}}
      ]
    }
  }
}

限制返回字段：

{
  "query": {"match_all": {}},
  "_source": ["title", "price", "category"]
}

3. 索引命名规范

# 按时间分割索引
logs-2025.10.14
logs-2025.10.13

# 按环境分离
products-prod
products-dev

# 使用别名
alias: products -> products-v2

4. 安全配置

# 启用 TLS（生产环境必须）
ES_URL=https://your-cluster.es.cloud:9243

# 不跳过证书验证
ES_SSL_SKIP_VERIFY=false

# 使用受限权限的 API Key
# 仅授予必要的索引和操作权限

5. 监控和日志

# 启用 Docker 日志
docker run --rm \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  -e ES_URL -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch stdio

常见问题

Q: 如何获取 Elasticsearch API Key？

# 方法 1：使用 Kibana UI
# 进入 Stack Management > API Keys > Create API key

# 方法 2：使用 REST API
curl -X POST "https://your-cluster:9243/_security/api_key" \
  -u elastic:password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mcp-server-key",
    "expiration": "30d",
    "role_descriptors": {
      "mcp_role": {
        "cluster": ["monitor"],
        "index": [{
          "names": ["*"],
          "privileges": ["read"]
        }]
      }
    }
  }'

Q: 支持哪些 Elasticsearch 版本？

支持 Elasticsearch 8.x 和 9.x 版本。建议使用最新的稳定版本以获得最佳性能和功能。

Q: 如何处理大量数据的查询？

{
  "query": {"match_all": {}},
  "size": 100,
  "from": 0,
  "sort": [{"timestamp": "desc"}],
  "_source": ["essential_fields_only"]
}

使用分页（from + size）或 Scroll API 处理大结果集。

Q: 如何调试连接问题？

# 1. 测试 Elasticsearch 连接
curl -u elastic:password https://your-cluster.es.cloud:9243/_cluster/health

# 2. 检查 Docker 容器日志
docker logs <container-id>

# 3. 验证环境变量
docker run --rm -e ES_URL -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch stdio --debug

Q: 性能如何？

查询延迟: <100ms（小数据集）、<1s（大数据集）
吞吐量: 取决于 Elasticsearch 集群配置
内存占用: ~50MB（Rust 运行时）

Q: 是否支持 Elasticsearch Cloud？

是的，完全支持 Elasticsearch Cloud（Elastic Cloud）。只需配置正确的 ES_URL 和认证信息即可。

评分详情

维度	评分	说明
功能性	4.8/5.0	覆盖核心搜索功能，支持 Query DSL 和 ES
文档质量	4.6/5.0	官方文档清晰，示例丰富
社区活跃度	4.7/5.0	Elastic 官方维护，社区支持良好
维护状态	4.8/5.0	定期更新，持续改进
代码质量	4.7/5.0	Rust 实现，性能优秀，内存安全
综合评分	4.7/5.0	企业级搜索的最佳 MCP 选择

总结

Elasticsearch MCP Server 是连接 AI Agent 与企业搜索引擎的理想桥梁。它将 Elasticsearch 的强大搜索和分析能力与 MCP 协议完美结合，为开发者提供了简单而强大的接口。

推荐指数: ⭐⭐⭐⭐⭐ (5/5)

适合你的情况：

✅ 需要企业级搜索功能
✅ 处理大规模日志和数据分析
✅ 构建智能知识库
✅ 实时数据监控和告警
✅ 已有 Elasticsearch 基础设施

不适合的情况：

❌ 简单键值存储需求
❌ 小型项目（设置成本较高）
❌ 不需要全文搜索功能
❌ 预算有限（Elasticsearch 资源消耗较大）

Elasticsearch MCP Server - 企业级搜索引擎的智能桥梁

概述

核心特性

工具列表

1. list_indices

2. get_mappings

3. search

4. esql

5. get_shards

配置方式

环境变量

Claude Desktop 配置

Docker 部署

1. Stdio 协议（Claude Desktop）

2. Streamable-HTTP（推荐用于 Web 应用）

3. SSE 协议

使用用户名密码认证

使用场景

1. 日志分析与故障排查

2. 电商产品搜索

3. 实时数据监控

4. 企业搜索应用

5. 数据分析与报表

技术架构

系统组件

数据流程

支持的协议

与其他搜索方案对比

最佳实践

1. 选择合适的认证方式

2. 优化查询性能

3. 索引命名规范

4. 安全配置

5. 监控和日志

常见问题

Q: 如何获取 Elasticsearch API Key？

Q: 支持哪些 Elasticsearch 版本？

Q: 如何处理大量数据的查询？

Q: 如何调试连接问题？

Q: 性能如何？

Q: 是否支持 Elasticsearch Cloud？

评分详情

总结

相关资源