📌Overview

Purpose: To facilitate seamless interaction with Elasticsearch data through natural language queries using the Model Context Protocol (MCP).

Overview: The Elasticsearch MCP Server enables MCP clients, such as Claude Desktop, to connect directly to Elasticsearch data. This server streamlines communication and data retrieval via natural language, enhancing user experience and accessibility to Elasticsearch indices and queries.

Key Features:

List Indices: Users can view all available indices in Elasticsearch, allowing for easy exploration of data structures.
Get Mappings: This feature allows inspection of field mappings for specific indices, aiding in understanding the schema of the data.
Search: Execute complex Elasticsearch queries using full Query DSL capabilities, complete with automatic highlighting for result clarity.

Elasticsearch MCP Server

Connect to your Elasticsearch data directly from any MCP Client (like Claude Desktop) using the Model Context Protocol (MCP).

This server connects agents to your Elasticsearch data, allowing you to interact with your Elasticsearch indices through natural language conversations.

Available Tools

list_indices: List all available Elasticsearch indices
get_mappings: Get field mappings for a specific Elasticsearch index
search: Perform an Elasticsearch search with the provided query DSL
get_shards: Get shard information for all or specific indices

Prerequisites

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

Installation & Setup

Using the Published NPM Package

The easiest way to use Elasticsearch MCP Server is through the published npm package.

Configure MCP Client

Open your MCP Client. Here we are configuring Claude Desktop.
Go to Settings > Developer > MCP Servers
Click Edit Config and add a new MCP Server with the following configuration:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@elastic/mcp-server-elasticsearch"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Start a Conversation
- Open a new conversation in your MCP Client
- The MCP server should connect automatically
- You can now ask questions about your Elasticsearch data

Configuration Options

You must provide either an API key or both username and password for authentication.

Environment Variable	Description	Required
`ES_URL`	Your Elasticsearch instance URL	Yes
`ES_API_KEY`	Elasticsearch API key for authentication	No
`ES_USERNAME`	Elasticsearch username for basic authentication	No
`ES_PASSWORD`	Elasticsearch password for basic authentication	No
`ES_CA_CERT`	Path to custom CA certificate for Elasticsearch SSL/TLS	No

Developing Locally

If you want to modify or extend the MCP Server, follow these local development steps.

Use the correct Node.js version
```
nvm use
```
Install Dependencies
```
npm install
```
Build the Project
```
npm run build
```

Run locally in Claude Desktop App

Open Claude Desktop App
Go to Settings > Developer > MCP Servers
Click Edit Config and add a new MCP Server with the following configuration:

{
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "node",
      "args": [
        "/path/to/your/project/dist/index.js"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Debugging with MCP Inspector
```
ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector
```
This will start the MCP Inspector, allowing you to debug and analyze requests.

Contributing

We welcome contributions from the community! For details on how to contribute, please see Contributing Guidelines.

Example Questions

Here are some natural language queries you can try with your MCP Client.

"What indices do I have in my Elasticsearch cluster?"
"Show me the field mappings for the 'products' index."
"Find all orders over $500 from last month."
"Which products received the most 5-star reviews?"

How It Works

The MCP Client analyzes your request and determines which Elasticsearch operations are needed.
The MCP server carries out these operations (listing indices, fetching mappings, performing searches).
The MCP Client processes the results and presents them in a user-friendly format.

Security Best Practices

Avoid using cluster-admin privileges. Create dedicated API keys with limited scope and apply fine-grained access control at the index level to prevent unauthorized data access.

You can create a dedicated Elasticsearch API key with minimal permissions to control access to your data:

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 with a custom CA, verify that the certificate path is correct and the file is readable.
Look at the terminal output for error messages.

If you encounter issues, feel free to open an issue on the GitHub repository.