使用说明

非官方Elasticsearch MCP服务器

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

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

主要特点

综合工具170多种Elasticsearch操作，包括搜索、索引、集群管理、分析和专用工具
高级配置：具有环境变量验证的类型安全配置系统
安全控制：只读模式，具有严格/警告选项，用于安全生产监控
丰富的搜索：具有自动突出显示、聚合和SQL支持的高级搜索
批量操作：使用助手API进行高效的批量索引、更新和删除
集群监控：健康检查、节点统计和性能指标
错误处理：通过详细的日志记录和故障排除指南进行稳健的错误处理
自动检测监控：使用Grafana仪表板的Prometheus指标（自动检测并优雅降级）
断路器：具有连接池和速率限制的生产级弹性
多智能体开发：与15多个专业代理进行复杂的开发协调，以协调工作流程
LangSmith集成：人工智能交互的高级跟踪和性能监控
演出：基于Bun运行时构建，可实现最佳性能和现代JavaScript功能

先决条件

安装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

其他要求

包子：最新版本（推荐运行时）
弹性搜索：7.x或更高版本（建议使用8.x+）
MCP客户端：Claude Desktop或任何兼容MCP的客户端
Node.js：18+（如果需要，可以兼容npm）

安装

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

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

npx @elastic/mcp-server-elasticsearch

选项2：本地开发安装

克隆存储库：

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

安装依赖项：
```
bun install
```
构建项目：
```
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客户端（克劳德桌面）

添加到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数据的问题：

“我的集群中有哪些索引？”
“显示产品索引的字段映射”
“查找上个月所有超过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`	最大查询超时（ms）
`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`	请求超时（ms）
`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

弹性云

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_put_watch -创建或更新手表 （写入操作）
watcher_get_watch -获取手表定义
watcher_delete_watch -删除手表 （破坏性操作）
watcher_execute_watch -执行监视 （写入操作）
watcher_ack_watch -确认手表 （写入操作）
watcher_activate_watch -激活手表 （写入操作）
watcher_deactivate_watch -关闭手表 （写入操作）
watcher_stats -获取观察者统计信息
watcher_start -启动观察者服务 （写入操作）
watcher_stop -停止观察服务 （写入操作）

自动缩放

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

开发环境

克隆和设置：

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

创建开发环境：

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

启动开发服务器：
```
bun run dev
```
使用MCP检查器进行调试：
```
ES_URL=your-url ES_API_KEY=your-key bun run inspector
```
打开http://localhost:5173用于检查器界面。

测试配置

# 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

配置系统

服务器使用复杂的配置系统：

类型安全：Zod模式完全支持TypeScript
环境优先：通过环境变量进行配置
验证：启动时自动验证
分层：默认值→ 环境变量→ 验证
文档：用清晰的例子自我记录

只读模式实现

操作分类：按破坏潜力分类的工具
灵活的模式：严格封锁与警告模式
精细控制：按操作类型检查
日志集成：全面的审计跟踪

安全

最佳实践

使用API密钥：首选API密钥身份验证而不是用户名/密码
最小特权原则：使用最小权限创建专用API密钥
只读生产：启用生产监控的只读模式
网络安全：使用TLS/SSL进行连接
凭据管理：将凭据保存在环境变量中

创建安全的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检查员

对于调试MCP协议问题：

bun run inspector

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

开发工作流程

分叉和克隆存储库
创建要素分支从 main
进行更改通过测试

运行质量检查：

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

提交拉取请求描述清晰

代码规范

TypeScript：已启用严格类型检查
ESLint：使用提供的配置进行代码linting
更漂亮：使用提供的配置进行代码格式化
黄道带：配置的架构验证
测试：需要全面的测试覆盖率

许可证

此项目根据Apache许可证2.0获得许可。看许可证了解详情。

链接

演出

基于Bun运行时构建，实现最佳性能：

快速启动：快速服务器初始化
内存效率高：优化了内存使用
现代JavaScript：最新ECMAScript特性
原生TypeScript：开发中没有编译开销

**需要帮助？**查看我们的故障排除指南共同的解决方案。

使用说明

非官方Elasticsearch MCP服务器

主要特点

目录

先决条件

安装Bun

其他要求

安装

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

选项2：本地开发安装

快速开始

1.配置您的环境

2.验证配置

3.配置MCP客户端（克劳德桌面）

4.开始使用

配置

环境变量

必需变量

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

服务器配置

Elasticsearch配置

日志记录配置

配置示例

本地开发

API密钥生产

弹性云

使用TLS自托管

只读模式

严格模式（生产）

警告模式（开发）

可用工具

核心业务

文档操作

批量操作

搜索和分析

索引管理

模板管理

分析和术语分析

索引别名

群集管理

字段映射和SQL管理

索引生命周期管理（ILM）

丰富政策

观察者操作

自动缩放

高级操作

用法示例

自然语言查询

复杂搜索示例

行政操作

发展

可用脚本

开发环境

测试配置

建筑

项目结构

配置系统

只读模式实现

安全

最佳实践

创建安全的API密钥

只读模式操作

故障排除

常见问题

配置错误

连接问题

只读模式

调试模式

验证工具

MCP检查员

开发工作流程

代码规范

许可证

链接

演出

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

Flomo笔记服务

AI开发助手