使用说明

Elasticsearch MCP服务器

用其他语言阅读：英语, 中文

概述

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

特性

🔗 多协议支持：支持stdio、流式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镜像（推荐）

# Basic usage with local Elasticsearch
docker run --rm \
  -e ES_ADDRESSES=http://localhost:9200 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# HTTP mode for remote access
docker run -d -p 8080:8080 \
  -e MCP_PROTOCOL=http \
  -e ES_ADDRESSES=http://your-elasticsearch:9200 \
  ghcr.io/aeazer/mcp-elasticsearch:latest

# With authentication
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镜像

# Clone the repository
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch

# Build Docker image
docker build -t mcp-elasticsearch .

# Run the container
docker run -e ES_ADDRESSES=http://localhost:9200 -e ES_VERSION=8 mcp-elasticsearch

方法3：从源代码编译

# Clone the repository
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch

# Download dependencies and build
go mod download
go build -o mcp-elasticsearch main.go

# Run with environment variables
export ES_ADDRESSES=http://localhost:9200
export ES_VERSION=8
export MCP_PROTOCOL=stdio
./mcp-elasticsearch

方法4：桌面应用程序集成（光标、克劳德桌面等）

为了与支持MCP的桌面应用程序集成，您可以通过配置文件配置服务器：

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

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

# Option A: Install directly from GitHub (Recommended)
go install github.com/AeaZer/mcp-elasticsearch@latest

# Option B: Build from source
git clone https://github.com/AeaZer/mcp-elasticsearch.git
cd mcp-elasticsearch
go mod download
go build -o mcp-elasticsearch main.go

# Option C: Download pre-built binary (Windows only)
# Download mcp-elasticsearch.exe from GitHub Releases
# macOS and Linux users should use Option A or B

备注：Docker不适合桌面应用程序集成，因为它在这种情况下不支持stdio模式。请改用本机可执行文件。

第二步：使可执行文件可用

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

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

步骤3：创建MCP配置

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

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

克劳德桌面： 在适合您平台的位置创建或编辑配置。

配置示例

基本配置：

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

弹性云配置：

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

# Test the server endpoints
curl http://localhost:8080/health    # Health check
curl http://localhost:8080/mcp       # MCP endpoint (requires proper MCP client)

使用弹性云

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 endpoint (deprecated)
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_ADDRESSES`	Elasticsearch集群地址（逗号分隔）	`http://localhost:9200`
`ES_USERNAME`	基本身份验证的用户名	-
`ES_PASSWORD`	基本身份验证密码	-
`ES_API_KEY`	用于身份验证的API密钥	-
`ES_CLOUD_ID`	弹性云ID	-
`ES_SSL`	启用SSL/TLS	`false`
`ES_INSECURE_SKIP_VERIFY`	跳过SSL证书验证	`false`
`ES_TIMEOUT`	连接超时	`30s`
`ES_MAX_RETRIES`	最大重试次数	`3`
`ES_VERSION`	目标Elasticsearch版本（7、8或9）	`8`

MCP服务器配置

变量	描述	默认值
`MCP_SERVER_NAME`	MCP的服务器名称	`Elasticsearch MCP Server`
`MCP_SERVER_VERSION`	服务器版本	`1.0.0`
`MCP_PROTOCOL`	使用协议(`stdio`, `http`，或 `sse` -已弃用）	`http` （在Docker中）， `stdio` （本地）
`MCP_ADDRESS`	可流式传输的HTTP服务器地址（仅限HTTP模式）	`0.0.0.0` （在Docker中）， `localhost` （本地）
`MCP_PORT`	流式HTTP服务器端口（仅限HTTP模式）	`8080`

协议端点

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

标准协议

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

流式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协议

使用示例

标准模式（本机构建的默认模式）

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

流式HTTP模式（Docker的默认设置）

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

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

⚠️ 警告：SSE协议已弃用，不建议用于生产环境。请改用流式HTTP。

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

使用弹性云

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

发展

先决条件

达到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模式下运行时，服务器提供多个端点：

健康检查端点

# Check server health (publicly accessible)
curl http://localhost:8080/health

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

MCP协议端点

# MCP communication endpoint (requires MCP client)
# URL: http://localhost:8080/mcp
# This endpoint handles MCP protocol messages and tool calls
# Not directly accessible via simple HTTP GET requests

重要提示

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

错误处理

所有错误均在MCP工具结果中报告 isError: true，允许LLM适当地查看和处理错误。协议级错误保留用于特殊情况，如缺少工具或服务器故障。

故障排除

集装箱问题

集装箱立即出口：确保Docker容器使用HTTP协议
无法连接到Elasticsearch：使用 host.docker.internal:9200 而不是 localhost:9200 在Docker中
权限不足：检查Docker守护进程权限和映像访问

网络问题

连接被拒绝：验证Elasticsearch是否正在运行且可访问
SSL错误：设置 ES_INSECURE_SKIP_VERIFY=true 用于使用自签名证书进行测试

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

官方MCP Go SDK -Go的官方MCP实施
弹性 -官方Elasticsearch Go客户端
模型上下文协议 -协议规范

_{Built with ❤️ for the Go community}

使用说明

Elasticsearch MCP服务器

概述

特性

支持的工具

集群操作

索引管理

文档操作

搜索操作

批量操作

快速开始

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

方法2：构建Docker镜像

方法3：从源代码编译

方法4：桌面应用程序集成（光标、克劳德桌面等）

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

第二步：使可执行文件可用

步骤3：创建MCP配置

配置示例

步骤4：重新启动桌面应用程序

验证

Docker使用示例

HTTP服务器模式（推荐）

使用弹性云

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

使用Docker Compose

配置

Elasticsearch配置

MCP服务器配置

协议端点

标准协议

流式HTTP协议（推荐）

SSE协议（已弃用）

使用示例

标准模式（本机构建的默认模式）

流式HTTP模式（Docker的默认设置）

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

使用弹性云

发展

先决条件

建筑

测试

构建Docker镜像

工具使用示例

获取群集信息

创建索引

为文档建立索引

具有排序和字段选择功能的高级搜索

健康监测

健康检查端点

MCP协议端点

重要提示

错误处理

故障排除

集装箱问题

网络问题

贡献

许可证

致谢

相关 MCP

Markdown转换服务

Kubernetes集群管理MCP服务

MongoDB 数据库 MCP 服务器

Elasticsearch/OpenSearch MCP服务器

Kubernetes MCP服务器

Kubernetes MCP 服务器