Elasticsearch MCP Server

Read this in other languages: English, 中文

Overview

An Elasticsearch MCP (Model Context Protocol) server built on github.com/modelcontextprotocol/go-sdk, providing seamless integration with Elasticsearch 7, 8, and 9 versions.

Features

🔗 Multi-Protocol Support: Supports stdio, Streamable HTTP, and SSE protocols (SSE deprecated)
📊 Multi-Version Compatibility: Compatible with Elasticsearch 7, 8, and 9
⚙️ Environment Configuration: Configure via environment variables
🔧 Rich Toolset: Complete set of Elasticsearch operation tools
🌐 Production Ready: Docker support with optimized builds
🐳 Container Ready: Pre-built Docker images available

Supported Tools

Cluster Operations

es_cluster_info: Get cluster information and version details
es_cluster_health: Get cluster health status and metrics

Index Management

es_index_create: Create new indices with settings and mappings
es_index_delete: Delete existing indices
es_index_exists: Check if an index exists
es_index_list: List all indices with metadata

Document Operations

es_document_index: Index documents with optional ID
es_document_get: Retrieve documents by ID
es_document_update: Update existing documents
es_document_delete: Delete documents by ID

Search Operations

es_search: Execute search queries with filters, sorting, and field selection
- Supports: index, query, size, from, sort, _source
- Full Elasticsearch Query DSL support

Bulk Operations

es_bulk: Execute multiple operations in a single request

Quick Start

Choose one of the following methods to run the Elasticsearch MCP server:

Method 1: Use Pre-built Docker Image (Recommended)

# 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

Method 2: Build Docker Image

# 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

Method 3: Compile from Source

# 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

Method 4: Desktop Application Integration (Cursor, Claude Desktop, etc.)

For integration with desktop applications that support MCP, you can configure the server through a configuration file:

Step 1: Build or Install the Executable

First, ensure you have the mcp-elasticsearch executable available:

# 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

Note: Docker is not suitable for desktop application integration as it doesn't support stdio mode properly in this context. Use native executables instead.

Step 2: Make Executable Available

If you used go install (Option A), the executable is automatically placed in $GOPATH/bin or $GOBIN, which is typically already in your PATH environment variable.

If you built from source (Option B) or downloaded the pre-built binary (Option C), ensure the mcp-elasticsearch executable is in your system PATH environment variable, or use the full path in your configuration.

Step 3: Create MCP Configuration

Create or modify the MCP configuration file for your desktop application:

Cursor: Create or edit ~/.cursor/mcp.json (Linux/Mac) or %APPDATA%\Cursor\User\mcp.json (Windows)

Claude Desktop: Create or edit configuration in the appropriate location for your platform.

Configuration Examples

Basic Configuration:

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

With Authentication:

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

With API Key:

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

Elastic Cloud Configuration:

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

Using Full Path (if not in PATH):

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

Step 4: Restart Desktop Application

After creating or modifying the configuration file, restart your desktop application to load the new MCP server configuration.

Verification

Once configured, you should see Elasticsearch tools and resources available in your desktop application. The available tools include cluster operations, index management, document operations, search capabilities, and bulk operations as listed in the "Supported Tools" section above.

Docker Usage Examples

HTTP Server Mode (Recommended)

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)

With 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 Server Mode (Not Recommended - Deprecated)

⚠️ WARNING: SSE protocol is deprecated and not recommended for production use. Use HTTP mode instead.

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

Using Docker Compose

Create a docker-compose.yml file:

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"

Run with: docker-compose up -d

Configuration

All configuration is done via environment variables:

Elasticsearch Configuration

Variable	Description	Default
`ES_ADDRESSES`	Elasticsearch cluster addresses (comma-separated)	`http://localhost:9200`
`ES_USERNAME`	Username for basic authentication	-
`ES_PASSWORD`	Password for basic authentication	-
`ES_API_KEY`	API Key for authentication	-
`ES_CLOUD_ID`	Elastic Cloud ID	-
`ES_SSL`	Enable SSL/TLS	`false`
`ES_INSECURE_SKIP_VERIFY`	Skip SSL certificate verification	`false`
`ES_TIMEOUT`	Connection timeout	`30s`
`ES_MAX_RETRIES`	Maximum retry attempts	`3`
`ES_VERSION`	Target Elasticsearch version (7, 8, or 9)	`8`

MCP Server Configuration

Variable	Description	Default
`MCP_SERVER_NAME`	Server name for MCP	`Elasticsearch MCP Server`
`MCP_SERVER_VERSION`	Server version	`1.0.0`
`MCP_PROTOCOL`	Protocol to use (`stdio`, `http`, or `sse` - deprecated)	`http` (in Docker), `stdio` (native)
`MCP_ADDRESS`	Streamable HTTP server address (HTTP mode only)	`0.0.0.0` (in Docker), `localhost` (native)
`MCP_PORT`	Streamable HTTP server port (HTTP mode only)	`8080`

Protocol Endpoints

Different protocols use different access methods:

Stdio Protocol

Access method: Direct stdin/stdout communication
Use case: LLM tool integration (Claude Desktop, etc.)
Endpoint: N/A (direct process communication)

Streamable HTTP Protocol (Recommended)

MCP endpoint: http://host:port/mcp
Health check: http://host:port/health
Use case: Remote access, n8n integration, API usage
Example: http://localhost:8080/mcp

SSE Protocol (Deprecated)

MCP endpoint: http://host:port/sse
Use case: Legacy SSE clients (not recommended)
Example: http://localhost:8080/sse
⚠️ Warning: Deprecated, use HTTP protocol instead

Usage Examples

Stdio Mode (Default for native builds)

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

Streamable HTTP Mode (Default for Docker)

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

SSE Mode (Deprecated - Not Recommended)

⚠️ WARNING: SSE protocol is deprecated and not recommended for production use. Use Streamable HTTP instead.

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

Using with Elastic Cloud

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

Development

Prerequisites

Go 1.23 or higher
Access to an Elasticsearch cluster
Docker (optional, for containerized development)

Building

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

Testing

go test ./...

Building Docker Image

docker build -t mcp-elasticsearch .

Tool Usage Examples

Get Cluster Information

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

Create an Index

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

Index a Document

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

Advanced Search with Sorting and Field Selection

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

Health Monitoring

When running in HTTP mode, the server provides multiple endpoints:

Health Check Endpoint

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

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

MCP Protocol Endpoint

# 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

Important Notes

Health endpoint (/health): Simple HTTP GET for monitoring
MCP endpoint (/mcp): For MCP protocol communication only
SSE endpoint (/sse): Deprecated, avoid using

Error Handling

All errors are reported within the MCP tool results with isError: true, allowing LLMs to see and handle errors appropriately. Protocol-level errors are reserved for exceptional conditions like missing tools or server failures.

Troubleshooting

Container Issues

Container exits immediately: Ensure you're using HTTP protocol for Docker containers
Cannot connect to Elasticsearch: Use host.docker.internal:9200 instead of localhost:9200 in Docker
Permission denied: Check Docker daemon permissions and image access

Network Issues

Connection refused: Verify Elasticsearch is running and accessible
SSL errors: Set ES_INSECURE_SKIP_VERIFY=true for testing with self-signed certificates

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Official MCP Go SDK - Official MCP implementation for Go
Elastic - Official Elasticsearch Go client
Model Context Protocol - Protocol specification

_{Built with ❤️ for the Go community}

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
config		config
elasticsearch		elasticsearch
server		server
tools		tools
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

AeaZer/mcp-elasticsearch

Folders and files

Latest commit

History

Repository files navigation

Elasticsearch MCP Server

Overview

Features

Supported Tools

Cluster Operations

Index Management

Document Operations

Search Operations

Bulk Operations

Quick Start

Method 1: Use Pre-built Docker Image (Recommended)

Method 2: Build Docker Image

Method 3: Compile from Source

Method 4: Desktop Application Integration (Cursor, Claude Desktop, etc.)

Step 1: Build or Install the Executable

Step 2: Make Executable Available

Step 3: Create MCP Configuration

Configuration Examples

Step 4: Restart Desktop Application

Verification

Docker Usage Examples

HTTP Server Mode (Recommended)

With Elastic Cloud

SSE Server Mode (Not Recommended - Deprecated)

Using Docker Compose

Configuration

Elasticsearch Configuration

MCP Server Configuration

Protocol Endpoints

Stdio Protocol

Streamable HTTP Protocol (Recommended)

SSE Protocol (Deprecated)

Usage Examples

Stdio Mode (Default for native builds)

Streamable HTTP Mode (Default for Docker)

SSE Mode (Deprecated - Not Recommended)

Using with Elastic Cloud

Development

Prerequisites

Building

Testing

Building Docker Image

Tool Usage Examples

Get Cluster Information

Create an Index

Index a Document

Advanced Search with Sorting and Field Selection

Health Monitoring

Health Check Endpoint

MCP Protocol Endpoint

Important Notes

Error Handling

Troubleshooting

Container Issues

Network Issues

Contributing

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Languages

Packages