MCP Server Elasticsearch

🚀 Elasticsearch MCP Server

This project enables direct connection to your Elasticsearch data via MCP clients (e.g., Claude Desktop).

It uses the Model Context Protocol (MCP) to proxy connections to your Elasticsearch data, allowing you to interact with Elasticsearch indices through natural - language conversations.

✨ Features

• list_indices: List all available Elasticsearch indices.
• get_mappings: Retrieve the field mappings of a specific Elasticsearch index.
• Search: Execute an Elasticsearch search using the provided query DSL.
• get_shards: Get shard information for all or specific indices.

📦 Installation

Prerequisites

• An Elasticsearch instance.
• Elasticsearch authentication credentials (API key or username/password).
• An MCP client (e.g., Claude Desktop).

Installation Steps

Step 1: Install Elasticsearch

Install Elasticsearch following the official documentation.

Step 2: Configure Elasticsearch

Edit the elasticsearch.yml file and add the following content:

plugins.security.enabled: true
plugins.security.ssl.enabled: true

Restart the Elasticsearch service to apply the changes.

Connecting the MCP Client

Connect to Elasticsearch using an MCP client (e.g., Claude Desktop).

💻 Usage Examples

Basic Usage

You can view a demonstration at: https://github.com/user-attachments/assets/5dd292e1-a37b-4f1a-b8d5-765f14dfe0c0

Tool Functions

• list_indices: List all available Elasticsearch indices.
• get_mappings: Retrieve the field mappings of a specific Elasticsearch index.
• Search: Execute an Elasticsearch search using the provided query DSL.
• get_shards: Get shard information for all or specific indices.

🔧 Technical Details

Security Best Practices

⚠️ Important Note Avoid using cluster administrator privileges. Create a dedicated API key with minimal permissions and apply fine - grained access control at the index level to prevent unauthorized data access.

You can create a dedicated Elasticsearch API key with limited permissions:

POST /_security/api_key
{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

📄 License

This project is licensed under the Apache License 2.0.

🚧 Troubleshooting

• Ensure your MCP configuration is correct.
• Verify that your Elasticsearch URL is accessible from your machine.
• Check that your authentication credentials (API key or username/password) have the necessary permissions.
• If using SSL/TLS and a custom CA, verify that the certificate path is correct and the file is readable.
• Check the error messages in the terminal output.

If you encounter any issues, please open an issue in the GitHub repository.