mcp-elasticsearch

This MCP server exposes a comprehensive set of Elasticsearch tools via the MCP protocol. It supports cluster information and health checks, index management (create, delete, exist, list), document operations (index, get, update, delete), search with full Elasticsearch Query DSL capabilities, and bulk operations. The server can run in multiple modes, with Docker being the recommended method for quick deployment. To interact with the server, ensure your MCP client is configured to communicate over HTTP (or the protocol you choose) and point it at the server endpoint. Common workflows include checking cluster health, creating indices with proper mappings, indexing documents, performing searches with filters and sorting, and using bulk operations for batch processing.

Prerequisites

• Docker installed on your machine (for the recommended deployment method)
• Internet access to pull the pre-built Docker image

Install and run using Docker (Recommended)

1. Pull and run the pre-built image: docker run --rm -d
   -e MCP_PROTOCOL=http
   -e ES_ADDRESSES=http://localhost:9200
   -e ES_VERSION=8
   ghcr.io/aeazer/mcp-elasticsearch:latest

2. Verify the service is reachable (example health check): curl http://localhost:8080/health

3. If you need HTTP access from outside the host, publish the port: docker run -d -p 8080:8080
   -e MCP_PROTOCOL=http
   -e ES_ADDRESSES=http://your-elasticsearch:9200
   -e ES_VERSION=8
   ghcr.io/aeazer/mcp-elasticsearch:latest

Alternative: Build from source and run (advanced)

1. Ensure Go is installed and you have network access
2. Clone the repository and navigate to it
3. Build the Docker image locally or run the binary directly if provided
4. Run with the appropriate environment variables (ES_ADDRESSES, ES_VERSION, MCP_PROTOCOL)

Prerequisites recap:

• Docker or a suitable container runtime
• Access to an Elasticsearch instance (local or remote) at ES_ADDRESSES
• Optional: credentials (ES_USERNAME, ES_PASSWORD) and SSL settings if required

Tips and common considerations:

• ES_ADDRESSES must point to your Elasticsearch instance(s). For multiple addresses, separate with commas if supported by the deployment variant.
• ES_VERSION should reflect the Elasticsearch major version you’re targeting (e.g., 7, 8, or 9).
• If you’re exposing the MCP server publicly, secure it with network controls and consider enabling authentication in Elasitcsearch and at the MCP layer where supported.
• The README notes that SSE is deprecated; prefer HTTP mode for production integrations.
• When using Docker, you can easily switch to host networking or map ports to the host as needed (e.g., -p 8080:8080).
• For desktop integrations, you can configure via a JSON MCP config file with command and environment variables that mirror the docker run envs.
• Monitor resource usage and ensure Elasticsearch is reachable from the MCP server’s network namespace.
• If you encounter connectivity issues, verify FIREWALL rules, ES_ADDRESSES syntax, and that the Elasticsearch version is compatible with the MCP server build.