MCP Elasticsearch Server 🔍

MCP Elasticsearch 服务 🔍

一个为 AI 助手和其他 MCP 客户端提供 Elasticsearch 集成功能的 Model Context Protocol（MCP）服务。此服务可通过标准化接口查询 Elasticsearch 集群。

功能

• 🔐 多种身份验证方式：支持 API 密钥和用户名/密码身份验证
• 📊 索引管理：列出索引及其健康状态和文档数
• 🗺️ 架构发现：获取字段映射，以了解索引结构
• 🔍 高级搜索：执行支持聚合和排序的复杂 Elasticsearch 查询
• 📋 结构化响应：以 JSON 格式输出，并附带搜索元数据
• ⚡ 性能监控：跟踪查询执行时间
• 🎯 上下文感知：支持在正确处理上下文取消的情况下执行搜索

工具

list_indices

列出所有 Elasticsearch 索引，可按模式筛选。

参数：

• pattern（字符串，可选）：索引模式筛选条件（默认值："*"）

返回：

• 索引总数
• 索引详情（名称、健康状态、状态、文档数、大小）

get_index_mappings

获取一个或多个 Elasticsearch 索引的字段映射。

参数：

• index（字符串，必需）：索引名称或模式

返回：

• 指定索引的完整字段映射

search

执行全面支持 DSL 的 Elasticsearch 搜索查询。

参数：

• index（字符串，必需）：要搜索的索引名称或模式
• query（字符串，可选）：以 JSON 格式提供的 Elasticsearch 查询 DSL（默认值："{}"）
• 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

安装

# Clone and build
git clone <repository>
cd mcp-elasticsearch
go mod download
go build -o bin/mcp-elasticsearch .

# Install to system
sudo install bin/mcp-elasticsearch /usr/local/bin/

使用方法

直接执行

# With API key
ES_URL="https://your-cluster.com" ES_API_KEY="your-api-key" mcp-elasticsearch

# With basic auth
ES_URL="https://your-cluster.com" ES_USERNAME="user" ES_PASSWORD="pass" mcp-elasticsearch

# With custom logging
ES_URL="https://your-cluster.com" ES_API_KEY="key" MCP_ES_LOG_LEVEL=debug mcp-elasticsearch

与 Claude Desktop 集成

添加到 Claude 配置中：

{
  "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：

{
  "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"
      }
    }
  }
}

查询示例

列出所有索引

{
  "tool": "list_indices",
  "parameters": {
    "pattern": "*"
  }
}

仅列出日志索引

{
  "tool": "list_indices", 
  "parameters": {
    "pattern": "logs-*"
  }
}

获取索引映射

{
  "tool": "get_index_mappings",
  "parameters": {
    "index": "logs-apm.error-*"
  }
}

简单搜索

{
  "tool": "search",
  "parameters": {
    "index": "logs-*",
    "query": "{\"match\": {\"service.name\": \"broker-api-b2b\"}}",
    "size": 50
  }
}

使用聚合进行复杂搜索

{
  "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}}}"
  }
}

使用排序进行搜索

{
  "tool": "search",
  "parameters": {
    "index": "logs-*",
    "query": "{\"match\": {\"log.level\": \"ERROR\"}}",
    "sort": "[{\"@timestamp\": {\"order\": \"desc\"}}]",
    "size": 20
  }
}

开发

# Install dependencies
go mod download

# Format code
gofmt -w .

# Run tests
go test -v ./...

# Build
go build -o bin/mcp-elasticsearch .

# Run with debug logging
MCP_ES_LOG_LEVEL=debug go run .

错误处理

服务会针对常见问题提供详细的错误消息：

• 身份验证失败：检查 API 密钥或凭据
• 找不到索引：确认索引名称和模式
• 查询语法错误：验证 Elasticsearch 查询 JSON
• 连接问题：确保 Elasticsearch 可访问

安全注意事项

• 安全存储 API 密钥和凭据
• 使用环境变量配置敏感信息
• 考虑 Elasticsearch 访问的网络安全
• 监控查询模式和资源使用情况

许可证

MIT License - 详情请参阅 LICENSE 文件。