内容
# MCP Elasticsearch 服务器 🔍
MCP（模型上下文协议）服务器，提供 Elasticsearch 集成能力，适用于 AI 助手和其他 MCP 客户端。该服务器通过标准化接口实现对 Elasticsearch 集群的查询。
## 功能
- **🔐 多种认证方式**：支持 API 密钥和用户名/密码认证
- **📊 索引管理**：列出索引及其健康状态和文档数量
- **🗺️ 模式发现**：检索字段映射以了解索引结构
- **🔍 高级搜索**：执行复杂的 Elasticsearch 查询，支持聚合和排序
- **📋 结构化响应**：JSON 格式输出，包含搜索元数据
- **⚡ 性能监控**：查询执行时间跟踪
- **🎯 上下文感知**：支持在适当上下文中取消搜索执行
## 工具
### list_indices
列出所有 Elasticsearch 索引，可选模式过滤。
**参数：**
- `pattern`（字符串，可选）：索引模式过滤器（默认为 "*"）
**返回结果：**
- 索引总数
- 索引详细信息（名称、健康状态、文档数量、大小）
### get_index_mappings
获取一个或多个 Elasticsearch 索引的字段映射。
**参数：**
- `index`（字符串，必填）：索引名称或模式
**返回结果：**
- 指定索引的完整字段映射
### search
执行 Elasticsearch 搜索查询，支持完整的 DSL。
**参数：**
- `index`（字符串，必填）：搜索的索引名称或模式
- `query`（字符串，可选）：Elasticsearch 查询 DSL 为 JSON（默认为 "{}"）
- `size`（数字，可选）：返回的最大文档数量（默认为 10，最大 10000）
- `sort`（字符串，可选）：排序规则为 JSON
- `track_total_hits`（布尔值，可选）：跟踪总命中数（默认为 true）
**返回结果：**
- 搜索结果，包括命中、聚合和元数据
## 配置
### 环境变量
#### Elasticsearch 配置
- `ES_URL`：Elasticsearch 集群 URL（必填）
- `ES_API_KEY`：认证的 API 密钥（可选）
- `ES_USERNAME`：基本认证的用户名（可选）
- `ES_PASSWORD`：基本认证的密码（可选）
#### 服务器配置
- `MCP_ES_SERVER_NAME`：服务器名称（默认为 "mcp-elasticsearch 🔍"）
#### 日志配置
- `MCP_ES_LOG_LEVEL`：日志级别（debug、info、warn、error、fatal）
- `MCP_ES_LOG_FORMAT`：日志格式（json、console）
- `MCP_ES_LOG_OUTPUT`：日志输出（stdout、stderr）
### 认证
您必须提供以下认证信息之一：
1. **API 密钥认证**：设置 `ES_API_KEY`
2. **基本认证**：同时设置 `ES_USERNAME` 和 `ES_PASSWORD`
## 安装
```bash
# 克隆并构建
git clone <仓库地址>
cd mcp-elasticsearch
go mod download
go build -o bin/mcp-elasticsearch .
# 安装到系统
sudo install bin/mcp-elasticsearch /usr/local/bin/
```
## 使用
### 直接执行
```bash
# 使用 API 密钥
ES_URL="https://your-cluster.com" ES_API_KEY="your-api-key" mcp-elasticsearch
# 使用基本认证
ES_URL="https://your-cluster.com" ES_USERNAME="user" ES_PASSWORD="pass" mcp-elasticsearch
# 自定义日志记录
ES_URL="https://your-cluster.com" ES_API_KEY="key" MCP_ES_LOG_LEVEL=debug mcp-elasticsearch
```
### 与 Claude Desktop 集成
添加到您的 Claude 配置：
```json
{
"mcpServers": {
"elasticsearch": {
"command": "mcp-elasticsearch",
"env": {
"ES_URL": "https://your-cluster.com",
"ES_API_KEY": "your-api-key",
"MCP_ES_LOG_LEVEL": "info"
}
}
}
}
```
### 与 ApMentor 集成
更新您的 `config.json`：
```json
{
"mcpServers": {
"elasticsearch-go": {
"command": "/usr/local/bin/mcp-elasticsearch",
"env": {
"ES_URL": "https://atani.es.eu-west-1.aws.found.io",
"ES_API_KEY": "your-api-key",
"MCP_ES_LOG_LEVEL": "info"
}
}
}
}
```
## 示例查询
### 列出所有索引
```json
{
"tool": "list_indices",
"parameters": {
"pattern": "*"
}
}
```
### 只列出日志索引
```json
{
"tool": "list_indices",
"parameters": {
"pattern": "logs-*"
}
}
```
### 获取索引映射
```json
{
"tool": "get_index_mappings",
"parameters": {
"index": "logs-apm.error-*"
}
}
```
### 简单搜索
```json
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"match\": {\"service.name\": \"broker-api-b2b\"}}",
"size": 50
}
}
```
### 复杂搜索与聚合
```json
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"bool\": {\"must\": [{\"term\": {\"service.name\": \"broker-api-b2b\"}}, {\"range\": {\"@timestamp\": {\"gte\": \"now-24h\"}}}]}}",
"size": 0,
"aggs": "{\"error_types\": {\"terms\": {\"field\": \"error.type.keyword\", \"size\": 10}}}"
}
}
```
### 搜索并排序
```json
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"match\": {\"log.level\": \"ERROR\"}}",
"sort": "[{\"@timestamp\": {\"order\": \"desc\"}}]",
"size": 20
}
}
```
## 开发
```bash
# 安装依赖
go mod download
# 格式化代码
gofmt -w .
# 运行测试
go test -v ./...
# 构建
go build -o bin/mcp-elasticsearch .
# 调试日志记录
MCP_ES_LOG_LEVEL=debug go run .
```
## 错误处理
服务器为常见问题提供详细错误信息：
- **认证失败**：检查您的 API 密钥或凭证
- **索引未找到**：验证索引名称和模式
- **查询语法错误**：验证您的 Elasticsearch 查询 JSON
- **连接问题**：确保 Elasticsearch 可访问
## 安全考虑
- 安全存储 API 密钥和凭证
- 使用环境变量进行敏感配置
- 考虑 Elasticsearch 访问的网络安全
- 监控查询模式和资源使用
## 许可证
MIT 许可证 - 参见 LICENSE 文件了解详情。
