elasticsearch

This Elasticsearch MCP Server provides a set of MCP tools that bridge a Spring AI MCP server with an Elasticsearch cluster. It exposes tools such as get_cluster_health, get_cluster_statistics, get_cat_mappings, get_cat_indices, get_cat_indices_by_name, get_cat_aliases, get_cat_aliases_by_name, get_document_search_by_index, get_shard_allocation, and get_shard_allocation_for_node. Each tool is accessible via standard MCP JSON-RPC calls and leverages the official Elasticsearch Java client to perform cluster health checks, mappings lookups, indexing, searching, and shard information. To use it, first ensure your MCP client is configured to connect to the running MCP server, and ensure your Elasticsearch instance is reachable with the necessary credentials if required by your environment.

Once the server is running, you can call tools by sending a JSON-RPC request specifying the tool name and parameters. For example, to check cluster health you would invoke the get_cluster_health tool with any needed parameters, and the server will return the health status and related metadata. You can chain results from tools like get_document_search_by_index with AI-generated queryDSL to perform targeted document searches within specific indices. The modular design supports multiple Elasticsearch versions and is structured to easily add new MCP tools or external integrations as you upgrade your Elasticsearch environment.

Prerequisites:

• JDK 17 or later
• Access to an Elasticsearch cluster (7.16 or later)
• Gradle (for building, if you prefer from source)
• MCP client (e.g., Claude Desktop) to interact with MCP server

1. Clone the repository git clone https://github.com/silbaram/elasticsearch-mcp-server.git cd elasticsearch-mcp-server

2. Configure your Elasticsearch connection Open mcp-server/src/main/resources/application.yml and set the Elasticsearch version and hosts, for example: elasticsearch: version: "8.6.1" search: hosts: - http://localhost:9200

3. Build the project ./gradlew build // The built JAR will typically be located at: // mcp-server/build/libs/elasticsearch-mcp-server-<version>.jar

4. Run the MCP server java -jar /path/to/elasticsearch-mcp-server.jar // Ensure the environment variables for Elasticsearch authentication are set if needed

5. Configure MCP client (example for Claude Desktop) In your MCP client, add a server configuration like: { "mcpServers": { "elasticsearch-server": { "command": "java", "args": [ "-Dusername=YOUR_USERNAME", "-Dpassword=YOUR_PASSWORD", "-jar", "/path/to/elasticsearch-mcp-server.jar" ] } } }

6. Test tools Use the MCP client to invoke tools such as get_cluster_health and get_cat_indices. Ensure your Elasticsearch cluster is accessible from the running server, and troubleshoot any connectivity errors in the logs.

Environment variables like ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, and ELASTICSEARCH_PASSWORD control how the server connects to Elasticsearch. If you run Elasticsearch behind TLS or with basic auth, set the appropriate credentials and possibly additional config in application.yml. The tooling is designed to be extensible; if you add new @Tool annotated methods, they will automatically be exposed as MCP tools. Ensure your MCP client supports JSON-RPC calls and points to the running server URL. If you encounter mapping or index compatibility issues, confirm the Elasticsearch version matches the configured client behavior (7.16+ required).