Unofficial Elasticsearch MCP Server

非官方 Elasticsearch MCP 服务

一个可用于生产环境的模型上下文协议（MCP）服务，可将 Claude Desktop 等 AI 助手连接到 Elasticsearch 集群。该服务通过自然语言交互提供全面的 Elasticsearch 操作，具备高级配置管理、安全控制和丰富的工具。

这是对官方 Elastic MCP 服务的全面增强，将核心工具从 4 个扩展到 170 多项专用操作，覆盖整个 Elasticsearch 生态系统。

主要功能

• 全面的工具支持：提供 170 多项 Elasticsearch 操作，包括搜索、索引、集群管理、分析和专用工具
• 高级配置：类型安全的配置系统，支持环境变量验证
• 安全控制：提供严格模式和警告模式的只读模式，可安全地监控生产环境
• 丰富的搜索功能：支持高级搜索、自动高亮、聚合和 SQL
• 批量操作：借助辅助 API 高效地批量索引、更新和删除
• 集群监控：健康检查、节点统计信息和性能指标
• 错误处理：稳健的错误处理、详细日志和故障排除指南
• 自动检测监控：提供 Prometheus 指标和 Grafana 仪表板（自动检测并优雅降级）
• 熔断器：具备连接池和速率限制的生产级弹性机制
• 多 Agent 开发：通过 15 个以上的专用 Agent 协调复杂开发流程
• LangSmith 集成：为 AI 交互提供高级追踪和性能监控
• 性能：基于 Bun 运行时构建，提供出色的性能和现代 JavaScript 特性

目录

• 先决条件
• 安装
• 快速开始
• 配置
• 可用工具
• 使用示例
• 开发
• 架构
• 安全
• 故障排除

先决条件

安装 Bun

本项目使用 Bun 作为 JavaScript 运行时，以获得出色的性能。可通过以下任一方式安装 Bun：

macOS/Linux：

curl -fsSL https://bun.sh/install | bash

Windows（PowerShell）：

irm bun.sh/install.ps1 | iex

包管理器：

# npm
npm install -g bun

# Homebrew (macOS)
brew install bun

# Scoop (Windows)
scoop install bun

验证安装：

bun --version

其他要求

• Bun：最新版本（推荐的运行时）
• Elasticsearch：7.x 或更高版本（推荐 8.x 及以上）
• MCP 客户端：Claude Desktop 或任何兼容 MCP 的客户端
• Node.js：18+（如有需要，用于兼容 npm）

安装

选项 1：使用已发布的 NPM 包（推荐）

使用 Elasticsearch MCP 服务的最简单方法：

npx @elastic/mcp-server-elasticsearch

选项 2：本地开发安装

1. 克隆代码仓库：

   git clone https://github.com/elastic/mcp-server-elasticsearch.git
   cd mcp-server-elasticsearch
   

2. 安装依赖项：

   bun install
   

3. 构建项目：

   bun run build
   

快速开始

1. 配置环境

根据模板创建 .env 文件：

cp .env.example .env

最小配置：

# Required
ES_URL=http://localhost:9200

# Authentication (choose one)
ES_API_KEY=your_api_key_here
# OR
ES_USERNAME=elastic
ES_PASSWORD=changeme

# Optional: Enable read-only mode for safety
READ_ONLY_MODE=false
LOG_LEVEL=info

2. 验证配置

# Basic validation
bun run validate-config

# Full validation with connection test
bun run validate-config:full

3. 配置 MCP 客户端（Claude Desktop）

将以下内容添加到 MCP 客户端配置中：

使用已发布的包：

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": ["-y", "@elastic/mcp-server-elasticsearch"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

用于本地开发：

{
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "bun",
      "args": ["run", "/path/to/your/project/src/index.ts"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

4. 开始使用

打开 MCP 客户端，开始询问有关 Elasticsearch 数据的问题：

• “我的集群中有哪些索引？”
• “显示 products 索引的字段映射”
• “查找上个月所有金额超过 $500 的订单”

配置

此服务提供全面的配置系统，支持类型安全验证和环境变量。

环境变量

必需变量

变量	描述	示例
ES_URL	Elasticsearch 服务 URL	http://localhost:9200

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

API 密钥身份验证（推荐）：

ES_API_KEY=your_api_key_here

用户名/密码身份验证：

ES_USERNAME=your_username
ES_PASSWORD=your_password

服务配置

变量	默认值	描述
MCP_SERVER_NAME	elasticsearch-mcp-server	服务标识
MCP_SERVER_VERSION	0.1.1	服务版本
READ_ONLY_MODE	false	启用只读模式
READ_ONLY_STRICT_MODE	true	对破坏性操作进行拦截还是警告
MCP_MAX_QUERY_TIMEOUT	30000	最大查询超时时间（毫秒）
MCP_MAX_RESULTS_PER_QUERY	1000	每次查询的最大结果数
MCP_TRANSPORT	stdio	传输模式（stdio 或 sse）
MCP_PORT	8080	服务端口（用于 SSE 模式）

Elasticsearch 配置

变量	默认值	描述
ES_CA_CERT	-	CA 证书文件路径
ES_MAX_RETRIES	3	最大重试次数
ES_REQUEST_TIMEOUT	30000	请求超时时间（毫秒）
ES_COMPRESSION	true	启用响应压缩
ES_ENABLE_META_HEADER	true	启用客户端元数据标头
ES_DISABLE_PROTOTYPE_POISONING_PROTECTION	true	禁用原型污染防护

日志配置

变量	默认值	描述
LOG_LEVEL	info	日志级别（debug、info、warn、error）
LOG_FORMAT	json	日志格式（json 或 text）
LOG_INCLUDE_METADATA	true	在日志中包含元数据

配置示例

本地开发

ES_URL=http://localhost:9200
LOG_LEVEL=debug
READ_ONLY_MODE=false

使用 API 密钥的生产环境

ES_URL=https://your-cluster.es.cloud.aws.com:443
ES_API_KEY=your_production_api_key
READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true
LOG_LEVEL=info
ES_MAX_RETRIES=5
ES_REQUEST_TIMEOUT=60000

Elastic Cloud

ES_URL=https://your-deployment.es.us-central1.gcp.cloud.es.io:443
ES_API_KEY=your_cloud_api_key
READ_ONLY_MODE=true
LOG_LEVEL=info

使用 TLS 的自托管环境

ES_URL=https://elasticsearch.company.com:9200
ES_USERNAME=mcp_user
ES_PASSWORD=secure_password
ES_CA_CERT=/etc/ssl/certs/elasticsearch-ca.pem
READ_ONLY_MODE=true
LOG_LEVEL=warn

只读模式

该服务支持只读模式，以便在生产环境中安全运行：

严格模式（生产环境）

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true

• 拦截所有破坏性操作
• 对写入/删除操作返回错误响应
• 非常适合监控和分析

警告模式（开发环境）

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=false

• 允许执行操作，同时显示醒目的警告
• 记录破坏性操作的警告
• 非常适合测试和受控环境

可用工具

核心操作

• list_indices - 列出所有可用的 Elasticsearch 索引
• get_mappings - 获取索引的字段映射
• search - 执行搜索并自动突出显示匹配内容
• get_shards - 获取分片信息和分布情况

文档操作

• get_document - 按 ID 检索文档
• index_document - 创建或更新文档*（写入操作）*
• update_document - 更新现有文档*（写入操作）*
• delete_document - 删除文档*（破坏性操作）*
• document_exists - 检查文档是否存在

批量操作

• bulk_operations - 高效地批量创建/更新/删除*（写入/破坏性操作）*
• multi_get - 检索多个文档

搜索与分析

• execute_sql_query - 执行 SQL 查询
• count_documents - 统计匹配的文档数
• scroll_search - 处理大型结果集
• multi_search - 执行多个搜索
• update_by_query - 批量更新文档*（写入操作）*
• delete_by_query - 批量删除文档*（破坏性操作）*
• clear_scroll - 清除滚动上下文以释放资源

索引管理

• create_index - 创建新索引 （写入操作）
• delete_index - 删除索引 （破坏性操作）
• index_exists - 检查索引是否存在
• get_index - 获取索引信息
• get_index_settings - 获取索引设置
• update_index_settings - 修改索引设置 （写入操作）
• put_mapping - 更新索引映射 （写入操作）
• refresh_index - 强制刷新索引 （写入操作）
• flush_index - 强制刷新索引缓冲区 （写入操作）
• reindex_documents - 在索引之间复制/移动数据 （写入操作）

模板管理

• search_template - 执行已存储的搜索模板
• multi_search_template - 执行多个搜索模板
• get_index_template - 获取索引模板定义
• put_index_template - 创建或更新索引模板 （写入操作）
• delete_index_template - 删除索引模板 （破坏性操作）

分析与词项分析

• get_term_vectors - 获取文档的词项向量
• get_multi_term_vectors - 获取多个文档的词项向量

索引别名

• get_aliases - 获取索引别名
• put_alias - 创建索引别名 （写入操作）
• delete_alias - 删除索引别名 （破坏性操作）
• update_aliases - 原子性地更新多个别名 （写入操作）

集群管理

• get_cluster_health - 集群健康状态
• get_cluster_stats - 集群统计信息
• get_nodes_info - 节点信息
• get_nodes_stats - 节点统计信息

字段映射与 SQL 管理

• get_field_mapping - 获取指定字段的映射
• clear_sql_cursor - 清除 SQL 游标
• translate_sql_query - 将 SQL 转换为 Elasticsearch DSL

索引生命周期管理（ILM）

• ilm_get_lifecycle - 获取生命周期策略
• ilm_put_lifecycle - 创建或更新生命周期策略 （写入操作）
• ilm_delete_lifecycle - 删除生命周期策略 （破坏性操作）
• ilm_explain_lifecycle - 说明索引的生命周期状态
• ilm_get_status - 获取 ILM 状态
• ilm_start - 启动 ILM 插件 （写入操作）
• ilm_stop - 停止 ILM 插件 （写入操作）
• ilm_retry - 重试失败的生命周期步骤 （写入操作）
• ilm_remove_policy - 从索引中移除策略 （写入操作）
• ilm_move_to_step - 手动将索引移至生命周期步骤 （破坏性操作）
• ilm_migrate_to_data_tiers - 迁移至数据层 （破坏性操作）

丰富策略

• enrich_get_policy - 获取丰富策略信息
• enrich_put_policy - 创建丰富策略 （写入操作）
• enrich_delete_policy - 删除丰富策略 （破坏性操作）
• enrich_execute_policy - 执行丰富策略 （写入操作）
• enrich_stats - 获取丰富统计信息

Watcher 操作

• watcher_put_watch - 创建或更新监视 （写入操作）
• watcher_get_watch - 获取监视定义
• watcher_delete_watch - 删除监视 （破坏性操作）
• watcher_execute_watch - 执行监视 （写入操作）
• watcher_ack_watch - 确认监视 （写入操作）
• watcher_activate_watch - 激活监视 （写入操作）
• watcher_deactivate_watch - 停用监视 （写入操作）
• watcher_stats - 获取 Watcher 统计信息
• watcher_start - 启动 Watcher 服务 （写入操作）
• watcher_stop - 停止 Watcher 服务 （写入操作）

自动扩缩容

• autoscaling_get_policy - 获取自动扩缩容策略
• autoscaling_put_policy - 创建自动扩缩容策略 （写入操作）
• autoscaling_delete_policy - 删除自动扩缩容策略 （破坏性操作）
• autoscaling_get_capacity - 获取自动扩缩容容量

高级操作

• reindex_with_notifications - 重新索引并发送进度通知 （写入操作）
• bulk_index_with_progress - 批量索引并跟踪进度 （写入操作）
• elasticsearch_diagnostics - 全面的集群诊断
• analyze_timestamps - 分析时间戳字段，检查数据质量问题

使用示例

自然语言查询

"What indices do I have in my cluster?"
"Show me the field mappings for the 'products' index"
"Count how many documents are in the logs index"
"What's the health status of my cluster?"

复杂搜索示例

"Search for users with email containing 'gmail' in the users index"
"Find all error logs from the last 24 hours with severity high"
"Show me products with price between 100 and 500 sorted by popularity"
"Get aggregated sales data grouped by region and month"

管理操作

"Create a new index called 'user-analytics' with timestamp mapping"
"Show me the cluster health and node information"
"List all indices that haven't been accessed in the last week"
"Update the refresh interval for the logs index to 30 seconds"

开发

可用脚本

# Development
bun run dev # Start in development mode
bun run build # Build for production
bun run start # Start built server

# Configuration Management
bun run validate-config # Validate configuration
bun run validate-config:full # Full validation + connection test
bun run test-connection # Test Elasticsearch connection

# Quality & Testing
bun run test # Run tests
bun run lint # Lint code
bun run format # Format code

# Debugging
bun run inspector # Start MCP inspector for debugging

开发环境设置

1. 克隆并设置：

   git clone <repository>
   cd mcp-server-elasticsearch
   bun install
   

2. 创建开发环境：

   cp .env.example .env.dev
   # Edit .env.dev with your local settings
   

3. 启动开发服务器：

   bun run dev
   

4. 使用 MCP Inspector 调试：

   ES_URL=your-url ES_API_KEY=your-key bun run inspector
   

   打开 http://localhost:5173 访问 Inspector 界面。

测试配置

# Test configuration validity
bun run validate-config

# Test with connection verification
bun run validate-config:full --check-connection

# Show all configuration details
bun run validate-config --show-all

架构

项目结构

src/
 config.ts # Centralized configuration system
 index.ts # Entry point and server startup
 server.ts # MCP server creation and setup
 validation.ts # Environment and connection validation
 tools/ # Tool implementations
    index.ts # Tool registration
    core/ # Core operations (search, list, mappings)
    document/ # Document operations
    search/ # Advanced search operations
    index_management/ # Index management tools
    cluster/ # Cluster monitoring tools
    bulk/ # Bulk operations
    analytics/ # Analytics and term vectors
    alias/ # Index alias management
    template/ # Template management
    advanced/ # Advanced operations
    mapping/ # Field mapping tools
    ilm/ # Index Lifecycle Management
    enrich/ # Enrich policies
 utils/
     logger.ts # MCP-compatible logging system
     readOnlyMode.ts # Read-only mode management

配置系统

服务采用了完善的配置系统：

• **类型安全：**全面支持 TypeScript 和 Zod 架构
• **环境优先：**通过环境变量配置
• **验证：**启动时自动验证
• **分层：**默认值 → 环境变量 → 验证
• **文档：**提供清晰示例，实现自文档化

只读模式实现

• **操作分类：**根据工具的破坏性进行分类
• **灵活模式：**支持严格阻止和警告模式
• **精细控制：**按操作类型进行检查
• **日志集成：**提供全面的审计跟踪

安全

最佳实践

1. **使用 API 密钥：**优先使用 API 密钥身份验证，而非用户名/密码
2. **最小权限原则：**创建权限最少的专用 API 密钥
3. **生产环境只读：**为生产环境监控启用只读模式
4. **网络安全：**使用 TLS/SSL 进行连接
5. **凭据管理：**将凭据保存在环境变量中

创建安全的 API 密钥

POST /_security/api_key
{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["index-1", "index-2", "index-pattern-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}

只读模式操作

始终受保护（破坏性操作）：

• delete_document、delete_index、delete_by_query
• delete_alias、delete_index_template

受保护（写入/修改操作）：

• index_document、update_document、bulk_operations
• create_index、update_index_settings、put_mapping

始终允许（只读操作）：

• search、get_document、list_indices
• get_mappings、count_documents、get_cluster_health

故障排除

常见问题

配置错误

URL 格式无效：

Error: ES_URL is not a valid URL format

**解决方案：**确保 URL 包含协议：http:// 或 https://

缺少身份验证信息：

Error: Either ES_API_KEY or both ES_USERNAME and ES_PASSWORD must be provided

**解决方案：**提供完整的身份验证凭据

连接问题

连接被拒绝：

Error: ECONNREFUSED

**解决方案：**确认 Elasticsearch 正在运行且 URL 正确

SSL/TLS 问题：

Error: certificate verify failed

**解决方案：**使用 ES_CA_CERT 或检查证书配置

身份验证失败：

Error: 401 Unauthorized

**解决方案：**确认 API 密钥或用户名/密码正确

只读模式

操作被阻止：

 READ-ONLY MODE: DESTRUCTIVE DELETE operation blocked

**解决方案：**设置 READ_ONLY_MODE=false，或仅使用只读操作

调试模式

启用调试日志以便详细排查问题：

LOG_LEVEL=debug bun run dev

验证工具

# Check configuration
bun run validate-config

# Test connection
bun run validate-config:full

# Test specific operations
bun run test-connection

MCP Inspector

用于调试 MCP 协议问题：

bun run inspector

打开 http://localhost:6274 检查 MCP 通信。

开发工作流

1. 复刻并克隆此仓库
2. 从 main 创建功能分支
3. 进行更改并添加测试
4. 运行质量检查：

   bun run lint
   bun run format
   bun run test
   bun run validate-config
   

5. 提交拉取请求并附上清晰说明

代码规范

• **TypeScript：**已启用严格类型检查
• **ESLint：**使用提供的配置检查代码
• **Prettier：**使用提供的配置格式化代码
• **Zod：**验证配置架构
• **测试：**必须提供全面的测试覆盖

许可证

本项目采用 Apache License 2.0 许可。详情请参阅 LICENSE。

链接

• Model Context Protocol
• Elasticsearch Documentation
• Bun Runtime
• Claude Desktop

性能

基于 Bun 运行时构建，性能卓越：

• 快速启动：快速初始化服务
• 内存高效：优化内存使用
• 现代 JavaScript：采用最新的 ECMAScript 特性
• 原生 TypeScript：开发过程中无需编译开销

---

**需要帮助？**查看我们的故障排除指南，了解常见解决方案。