星战科技xingzhan.cloud
返回市场
麦普-弹性搜索

麦普-弹性搜索

作者：AeaZer6 星标更新：2025-07-31
安装使用来源：spider==github.com

项目介绍

Elasticsearch MCP 服务器

阅读其他语言版本：英文，中文

概述

基于 github.com/modelcontextprotocol/go-sdk 构建的 Elasticsearch MCP（模型上下文协议）服务器，提供与 Elasticsearch 7、8 和 9 版本的无缝集成。

功能

  • 🔗 多协议支持：支持 stdio、Streamable HTTP 和 SSE 协议（SSE 已弃用）
  • 📊 多版本兼容性：兼容 Elasticsearch 7、8 和 9
  • ⚙️ 环境配置：通过环境变量进行配置
  • 🔧 丰富的工具集：完整的 Elasticsearch 操作工具集
  • 🌐 生产就绪：支持 Docker 并进行了优化构建
  • 🐳 容器就绪：预构建的 Docker 镜像可用

支持的工具

集群操作

  • es_cluster_info：获取集群信息和版本详情
  • es_cluster_health：获取集群健康状态和指标

索引管理

  • es_index_create：创建具有设置和映射的新索引
  • es_index_delete：删除现有索引
  • es_index_exists：检查索引是否存在
  • es_index_list：列出所有索引及其元数据

文档操作

  • es_document_index：使用可选ID索引文档
  • es_document_get：通过ID检索文档
  • es_document_update：更新现有文档
  • es_document_delete：通过ID删除文档

搜索操作

  • es_search：执行带有过滤器、排序和字段选择的搜索查询
    • 支持：index、query、size、from、sort、_source
    • 完整的 Elasticsearch 查询 DSL 支持

批量操作

  • es_bulk：在一个请求中执行多个操作

快速开始

选择以下方法之一运行 Elasticsearch MCP 服务器：

方法 1：使用预构建的 Docker 镜像（推荐）

# 基本用法，本地 Elasticsearch
docker run --rm \
  -e ES_ADDRESSES=http://localhost:9200 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# HTTP 模式，远程访问
docker run -d -p 8080:8080 \
  -e MCP_PROTOCOL=http \
  -e ES_ADDRESSES=http://your-elasticsearch:9200 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# 使用认证
docker run -d -p 8080:8080 \
  -e MCP_PROTOCOL=http \
  -e ES_ADDRESSES=https://your-elasticsearch:9200 \
  -e ES_USERNAME=elastic \
  -e ES_PASSWORD=your-password \
  -e ES_SSL=true \
  ghcr.io/aeazer/mcp-elasticsearch:latest

方法 2：构建 Docker 镜像

# 克隆仓库
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch

# 构建 Docker 镜像
docker build -t mcp-elasticsearch .

# 运行容器
docker run -e ES_ADDRESSES=http://localhost:9200 -e ES_VERSION=8 mcp-elasticsearch

方法 3：从源代码编译

# 克隆仓库
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch

# 下载依赖并构建
go mod download
go build -o mcp-elasticsearch main.go

# 使用环境变量运行
export ES_ADDRESSES=http://localhost:9200
export ES_VERSION=8
export MCP_PROTOCOL=stdio
./mcp-elasticsearch

方法 4：桌面应用集成（如 Cursor、Claude Desktop 等）

对于支持 MCP 的桌面应用集成，可以通过配置文件来配置服务器：

步骤 1：构建或安装可执行文件

首先确保你有可用的 mcp-elasticsearch 可执行文件：

# 选项 A：直接从 GitHub 安装（推荐）
go install github.com/AeaZer/mcp-elasticsearch@latest

# 选项 B：从源代码构建
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch
go mod download
go build -o mcp-elasticsearch main.go

# 选项 C：下载预构建的二进制文件（仅限 Windows）
# 从 GitHub Releases 下载 mcp-elasticsearch.exe
# macOS 和 Linux 用户应使用选项 A 或 B

注意：Docker 不适合桌面应用集成，因为它在这种情况下不完全支持 stdio 模式。请使用原生可执行文件。

步骤 2：使可执行文件可用

如果你使用了 go install（选项 A），可执行文件会自动放置在 $GOPATH/bin 或 $GOBIN 中，这通常已经在你的 PATH 环境变量中。

如果你是从源代码构建（选项 B）或下载了预构建的二进制文件（选项 C），请确保 mcp-elasticsearch 可执行文件在你的系统 PATH 环境变量中，或者在配置中使用完整路径。

步骤 3：创建 MCP 配置

创建或修改桌面应用的 MCP 配置文件：

Cursor：创建或编辑 ~/.cursor/mcp.json（Linux/Mac）或 %APPDATA%\Cursor\User\mcp.json（Windows）

Claude Desktop：在适当的位置创建或编辑配置。

配置示例

基本配置：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "mcp-elasticsearch",
      "env": {
        "ES_ADDRESSES": "http://localhost:9200",
        "ES_VERSION": "8"
      }
    }
  }
}

带认证：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "mcp-elasticsearch",
      "env": {
        "ES_ADDRESSES": "https://your-elasticsearch.com:9200",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your-password",
        "ES_VERSION": "8",
        "ES_SSL": "true"
      }
    }
  }
}

带 API 密钥：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "mcp-elasticsearch",
      "env": {
        "ES_ADDRESSES": "https://your-elasticsearch.com:9200",
        "ES_API_KEY": "your-api-key",
        "ES_VERSION": "8"
      }
    }
  }
}

Elastic Cloud 配置：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "mcp-elasticsearch",
      "env": {
        "ES_CLOUD_ID": "your-cloud-id",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your-password",
        "ES_VERSION": "8"
      }
    }
  }
}

使用完整路径（如果不在 PATH 中）：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "/full/path/to/mcp-elasticsearch",
      "env": {
        "ES_ADDRESSES": "http://localhost:9200",
        "ES_VERSION": "8"
      }
    }
  }
}

步骤 4：重启桌面应用

创建或修改配置文件后，请重启桌面应用以加载新的 MCP 服务器配置。

验证

配置完成后，你应该能在桌面应用中看到 Elasticsearch 工具和资源。可用的工具包括集群操作、索引管理、文档操作、搜索能力和批量操作，如上“支持的工具”部分所述。

Docker 使用示例

HTTP 服务器模式（推荐）

docker run -d -p 8080:8080 \
  --name mcp-elasticsearch \
  -e MCP_PROTOCOL=http \
  -e ES_ADDRESSES=http://host.docker.internal:9200 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# 测试服务器端点
curl http://localhost:8080/health    # 健康检查
curl http://localhost:8080/mcp       # MCP 端点（需要适当的 MCP 客户端）

使用 Elastic Cloud

docker run -d -p 8080:8080 \
  -e MCP_PROTOCOL=http \
  -e ES_CLOUD_ID="your-cloud-id" \
  -e ES_USERNAME=elastic \
  -e ES_PASSWORD="your-password" \
  -e ES_VERSION=8 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

SSE 服务器模式（不推荐 - 已弃用）

⚠️ 警告：SSE 协议已弃用，不建议用于生产用途。请使用 HTTP 模式。

docker run -d -p 8080:8080 \
  --name mcp-elasticsearch-sse \
  -e MCP_PROTOCOL=sse \
  -e ES_ADDRESSES=http://host.docker.internal:9200 \
  -e ES_VERSION=8 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# SSE 端点（已弃用）
curl http://localhost:8080/sse

使用 Docker Compose

创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  mcp-elasticsearch:
    image: ghcr.io/aeazer/mcp-elasticsearch:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_PROTOCOL=http
      - ES_ADDRESSES=http://elasticsearch:9200
      - ES_VERSION=8
    depends_on:
      - elasticsearch
    
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"

运行：docker-compose up -d

配置

所有配置均通过环境变量完成：

Elasticsearch 配置

变量描述默认值
ES_ADDRESSESElasticsearch 集群地址（逗号分隔）http://localhost:9200
ES_USERNAME基本认证用户名-
ES_PASSWORD基本认证密码-
ES_API_KEY认证 API 密钥-
ES_CLOUD_IDElastic Cloud ID-
ES_SSL启用 SSL/TLSfalse
ES_INSECURE_SKIP_VERIFY跳过 SSL 证书验证false
ES_TIMEOUT连接超时30s
ES_MAX_RETRIES最大重试次数3
ES_VERSION目标 Elasticsearch 版本（7、8 或 9）8

MCP 服务器配置

变量描述默认值
MCP_SERVER_NAMEMCP 服务器名称Elasticsearch MCP Server
MCP_SERVER_VERSION服务器版本1.0.0
MCP_PROTOCOL使用的协议（stdio、http 或 sse - 已弃用）http（在 Docker 中），stdio（原生）
MCP_ADDRESSStreamable HTTP 服务器地址（仅 HTTP 模式）0.0.0.0（在 Docker 中），localhost（原生）
MCP_PORTStreamable HTTP 服务器端口（仅 HTTP 模式）8080

协议端点

不同的协议使用不同的访问方法：

Stdio 协议

  • 访问方法：直接 stdin/stdout 通信
  • 使用场景：LLM 工具集成（Claude Desktop 等）
  • 端点：N/A（直接进程通信）

Streamable HTTP 协议（推荐）

  • MCP 端点：http://host:port/mcp
  • 健康检查：http://host:port/health
  • 使用场景：远程访问、n8n 集成、API 使用
  • 示例：http://localhost:8080/mcp

SSE 协议（已弃用）

  • MCP 端点：http://host:port/sse
  • 使用场景：遗留 SSE 客户端（不推荐）
  • 示例：http://localhost:8080/sse
  • ⚠️ 警告：已弃用，请使用 HTTP 协议

使用示例

Stdio 模式（默认为原生构建）

export ES_ADDRESSES=http://localhost:9200
export MCP_PROTOCOL=stdio
./mcp-elasticsearch

Streamable HTTP 模式（默认为 Docker）

export ES_ADDRESSES=http://localhost:9200
export MCP_PROTOCOL=http
export MCP_PORT=8080
./mcp-elasticsearch

SSE 模式（已弃用 - 不推荐）

⚠️ 警告：SSE 协议已弃用，不建议用于生产用途。请使用 Streamable HTTP。

export ES_ADDRESSES=http://localhost:9200
export MCP_PROTOCOL=sse
export MCP_PORT=8080
./mcp-elasticsearch

使用 Elastic Cloud

export ES_CLOUD_ID=your_cloud_id
export ES_USERNAME=elastic
export ES_PASSWORD=your_password
export ES_VERSION=8
./mcp-elasticsearch

开发

前提条件

  • Go 1.23 或更高版本
  • 对 Elasticsearch 集群的访问权限
  • Docker（可选，用于容器化开发）

构建

go mod download
go build -o mcp-elasticsearch main.go

测试

go test ./...

构建 Docker 镜像

docker build -t mcp-elasticsearch .

工具使用示例

获取集群信息

{
  "tool": "es_cluster_info",
  "arguments": {}
}

创建索引

{
  "tool": "es_index_create",
  "arguments": {
    "index": "my-index",
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "title": {"type": "text"},
        "timestamp": {"type": "date"}
      }
    }
  }
}

索引文档

{
  "tool": "es_document_index",
  "arguments": {
    "index": "my-index",
    "id": "doc1",
    "body": {
      "title": "Hello World",
      "content": "This is a test document",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
}

带排序和字段选择的高级搜索

{
  "tool": "es_search",
  "arguments": {
    "index": "my-index",
    "query": {
      "bool": {
        "must": [
          {"match": {"title": "Hello"}}
        ],
        "filter": [
          {"range": {"timestamp": {"gte": "2024-01-01"}}}
        ]
      }
    },
    "sort": [
      {"timestamp": {"order": "desc"}},
      {"_score": {"order": "desc"}}
    ],
    "_source": ["title", "content", "timestamp"],
    "size": 20,
    "from": 0
  }
}

健康监控

在 HTTP 模式下运行时，服务器提供了多个端点：

健康检查端点

# 检查服务器健康（公开访问）
curl http://localhost:8080/health

# 响应
{"status":"healthy","server":"elasticsearch-mcp"}

MCP 协议端点

# MCP 通信端点（需要 MCP 客户端）
# URL: http://localhost:8080/mcp
# 该端点处理 MCP 协议消息和工具调用
# 不能通过简单的 HTTP GET 请求直接访问

重要注意事项

  • 健康端点（/health）：简单的 HTTP GET 用于监控
  • MCP 端点（/mcp）：仅用于 MCP 协议通信
  • SSE 端点（/sse）：已弃用，避免使用

错误处理

所有错误都在 MCP 工具结果中报告，并带有 isError: true，允许 LLMs 查看并适当地处理错误。协议级别的错误保留给缺失工具或服务器故障等异常情况。

故障排除

容器问题

  • 容器立即退出：确保你为 Docker 容器使用的是 HTTP 协议
  • 无法连接到 Elasticsearch：在 Docker 中使用 host.docker.internal:9200 而不是 localhost:9200
  • 权限被拒绝：检查 Docker 守护程序权限和镜像访问

网络问题

  • 连接被拒绝：验证 Elasticsearch 是否正在运行且可访问
  • **SSL 错误