内容
# 非官方Elasticsearch MCP服务器
[](LICENSE)
[](https://www.npmjs.com/package/@elastic/mcp-server-elasticsearch)
[](https://bun.sh)
一个生产就绪的模型上下文协议（MCP）服务器，连接Claude Desktop等AI助手到Elasticsearch集群。该服务器通过自然语言交互提供全面的Elasticsearch操作，具有高级配置管理、安全控制和丰富的工具。
这是官方Elastic MCP服务器的全面增强，从4个核心工具扩展到170+个涵盖整个Elasticsearch生态系统的专业操作。
## 主要功能
- **丰富的工具**: 170+个Elasticsearch操作，包括搜索、索引、集群管理、分析、专业工具
- **高级配置**: 类型安全的配置系统，环境变量验证
- **安全控制**: 只读模式，严格/警告选项，用于安全生产监控
- **丰富的搜索**: 高级搜索，自动高亮、聚合、SQL支持
- **批量操作**: 高效的批量索引、更新、删除，带有帮助API
- **集群监控**: 健康检查、节点统计、性能指标
- **错误处理**: 强大的错误处理，详细日志和故障排除指南
- **自动检测监控**: Prometheus指标，Grafana仪表盘（自动检测和优雅降级）
- **熔断器**: 生产级弹性，连接池和速率限制
- **多代理开发**: 复杂的开发协调，15+个专业代理，用于编排工作流
- **LangSmith集成**: AI交互的高级跟踪和性能监控
- **性能**: 基于Bun运行时，优化性能和现代JavaScript功能
## 目录
- [前提条件](#前提条件)
- [安装](#安装)
- [快速入门](#快速入门)
- [配置](#配置)
- [可用工具](#可用工具)
- [使用示例](#使用示例)
- [开发](#开发)
- [架构](#架构)
- [安全](#安全)
- [故障排除](#故障排除)
## 前提条件
### 安装Bun
该项目使用[Bun](https://bun.sh)作为JavaScript运行时，以获得最佳性能。使用以下方法之一安装Bun：
**macOS/Linux:**
```bash
curl -fsSL https://bun.sh/install | bash
```
**Windows (PowerShell):**
```powershell
irm bun.sh/install.ps1 | iex
```
**包管理器：**
```bash
# npm
npm install -g bun
# Homebrew (macOS)
brew install bun
# Scoop (Windows)
scoop install bun
```
验证安装：
```bash
bun --version
```
### 其他要求
- **Bun**: 最新版本（推荐运行时）
- **Elasticsearch**: 7.x或更高版本（推荐8.x+）
- **MCP客户端**: Claude Desktop，或任何MCP兼容客户端
- **Node.js**: 18+（如果需要，适用于npm兼容性）
## 安装
### 选项1：使用已发布的NPM包（推荐）
使用Elasticsearch MCP服务器的最简单方法：
```bash
npx @elastic/mcp-server-elasticsearch
```
### 选项2：本地开发安装
1. **克隆仓库：**
```bash
git clone https://github.com/elastic/mcp-server-elasticsearch.git
cd mcp-server-elasticsearch
```
2. **安装依赖项：**
```bash
bun install
```
3. **构建项目：**
```bash
bun run build
```
## 快速入门
### 1. 配置您的环境
从模板创建`.env`文件：
```bash
cp .env.example .env
```
**最小配置：**
```bash
# 必需
ES_URL=http://localhost:9200
# 身份验证（选择一种）
ES_API_KEY=your_api_key_here
# 或
ES_USERNAME=elastic
ES_PASSWORD=changeme
# 可选：启用只读模式以确保安全
READ_ONLY_MODE=false
LOG_LEVEL=info
```
### 2. 验证配置
```bash
# 基本验证
bun run validate-config
# 完整验证与连接测试
bun run validate-config:full
```
### 3. 配置MCP客户端（Claude Desktop）
添加到您的MCP客户端配置：
**对于已发布的包：**
```json
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": ["-y", "@elastic/mcp-server-elasticsearch"],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}
```
**对于本地开发：**
```json
{
"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密钥身份验证（推荐）：**
```bash
ES_API_KEY=your_api_key_here
```
**用户名/密码身份验证：**
```bash
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` | 在日志中包含元数据 |
### 配置示例
#### 本地开发
```bash
ES_URL=http://localhost:9200
LOG_LEVEL=debug
READ_ONLY_MODE=false
```
#### 生产环境，使用API密钥
```bash
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
```bash
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
```bash
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
```
### 只读模式
服务器支持在生产中安全操作时的只读模式：
#### 严格模式（生产环境）
```bash
READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true
```
- **阻止**所有破坏性操作
- 返回写/删除操作的错误响应
- 适用于监控和分析
#### 警告模式（开发环境）
```bash
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`** - 分析时间戳字段的数据质量问题
## 使用示例
### 自然语言查询
```
"我的集群中有哪些索引？"
"显示我'products'索引的字段映射"
"统计logs索引中有多少文档"
"我的集群的健康状态是什么？"
```
### 复杂搜索示例
```
"在用户索引中搜索电子邮件中包含'gmail'的用户"
"查找过去24小时内严重程度为高的所有错误日志"
"显示价格在100和500之间、按受欢迎程度排序的产品"
"获取按地区和月份分组的聚合销售数据"
```
### 管理操作
```
"使用时间戳映射创建名为'user-analytics'的新索引"
"显示集群健康和节点信息"
"列出过去一周未被访问的所有索引"
"将logs索引的刷新间隔更新为30秒"
```
## 开发
### 可用脚本
```bash
# 开发
bun run dev # 以开发模式启动
bun run build # 为生产环境构建
bun run start # 启动已构建的服务器
# 配置管理
bun run validate-config # 验证配置
bun run validate-config:full # 完整验证 + 连接测试
bun run test-connection # 测试Elasticsearch连接
# 质量和测试
bun run test # 运行测试
bun run lint # 代码检查
bun run format # 代码格式化
# 调试
bun run inspector # 启动MCP检查器进行调试
```
### 开发设置
1. **克隆和设置：**
```bash
git clone <仓库>
cd mcp-server-elasticsearch
bun install
```
2. **创建开发环境：**
```bash
cp .env.example .env.dev
# 使用本地设置编辑.env.dev
```
3. **启动开发服务器：**
```bash
bun run dev
```
4. **使用MCP检查器调试：**
```bash
ES_URL=your-url ES_API_KEY=your-key bun run inspector
```
打开 http://localhost:5173 访问检查器界面。
### 测试配置
```bash
# 测试配置有效性
bun run validate-config
# 测试连接验证
bun run validate-config:full --check-connection
# 显示所有配置详细信息
bun run validate-config --show-all
```
## 架构
### 项目结构
```
src/
config.ts # 集中配置系统
index.ts # 入口点和服务器启动
server.ts # MCP服务器创建和设置
validation.ts # 环境和连接验证
tools/ # 工具实现
index.ts # 工具注册
core/ # 核心操作（搜索、列表、映射）
document/ # 文档操作
search/ # 高级搜索操作
index_management/ # 索引管理工具
cluster/ # 集群监控工具
bulk/ # 批量操作
analytics/ # 分析和词项向量
alias/ # 索引别名管理
template/ # 模板管理
advanced/ # 高级操作
mapping/ # 字段映射工具
ilm/ # 索引生命周期管理
enrich/ # 丰富策略
utils/
logger.ts # MCP兼容的日志系统
readOnlyMode.ts # 只读模式管理
```
### 配置系统
服务器使用复杂的配置系统：
- **类型安全**: 完整的TypeScript支持，带有Zod模式
- **环境优先**: 通过环境变量进行配置
- **验证**: 启动时自动验证
- **分层**: 默认值 → 环境变量 → 验证
- **文档**: 自我记录，带有清晰的示例
### 只读模式实现
- **操作分类**: 工具按破坏潜力分类
- **灵活的模式**: 严格阻止与警告模式
- **粒度控制**: 每个操作类型检查
- **日志集成**: 全面的审计轨迹
## 安全
### 最佳实践
1. **使用API密钥**: 优先使用API密钥身份验证而非用户名/密码
2. **最小权限原则**: 创建具有最小权限的专用API密钥
3. **生产只读**: 为生产监控启用只读模式
4. **网络安全**: 对连接使用TLS/SSL
5. **凭证管理**: 将凭证存储在环境变量中
### 创建安全 API 密钥
```bash
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` 或仅使用只读操作
### 调试模式
启用详细故障排除的调试日志记录：
```bash
LOG_LEVEL=debug bun run dev
```
### 验证工具
```bash
# 检查配置
bun run validate-config
# 测试连接
bun run validate-config:full
# 测试特定操作
bun run test-connection
```
### MCP 检查器
用于调试 MCP 协议问题：
```bash
bun run inspector
```
打开 http://localhost:6274 以检查 MCP 通信。
### 开发工作流
1. **Fork 和克隆** 仓库
2. **从 `main` 创建功能分支**
3. **进行更改并添加测试**
4. **运行质量检查：**
```bash
bun run lint
bun run format
bun run test
bun run validate-config
```
5. **提交拉取请求并附上清晰的描述**
### 代码标准
- **TypeScript**：启用严格类型检查
- **ESLint**：使用提供的配置进行代码检查
- **Prettier**：使用提供的配置进行代码格式化
- **Zod**：用于配置的模式验证
- **测试**：需要全面的测试覆盖
## 许可证
该项目在 Apache License 2.0 下获得许可。有关详细信息，请参阅 [LICENSE](LICENSE)。
## 链接
- [模型上下文协议](https://modelcontextprotocol.io/)
- [Elasticsearch 文档](https://www.elastic.co/guide/)
- [Bun 运行时](https://bun.sh)
- [Claude Desktop](https://claude.ai/download)
## 性能
基于 Bun 运行时构建以获得最佳性能：
- **快速启动**：快速的服务器初始化
- **内存高效**：优化的内存使用
- **现代 JavaScript**：最新的 ECMAScript 功能
- **原生 TypeScript**：开发过程中无编译开销
---
**需要帮助？** 查看我们的 [故障排除指南](#troubleshooting) 以获取常见解决方案。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器