home / mcp / elasticsearch mcp server

Elasticsearch MCP Server

Provides direct access to Elasticsearch data via MCP with index listing, mappings, searches, and shard info.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ampcome-mcps-elasticsearch-mcp": {
      "url": "https://mcp.example.com/elasticsearch",
      "headers": {
        "ES_URL": "https://es.example.com",
        "ES_API_KEY": "svc-abc123",
        "ES_CA_CERT": "/path/to/ca.pem",
        "ES_VERSION": "9.x",
        "ES_PASSWORD": "password",
        "ES_USERNAME": "elastic",
        "ES_PATH_PREFIX": "/es",
        "ES_SSL_SKIP_VERIFY": "1"
      }
    }
  }
}

You can connect to your Elasticsearch data directly from an MCP Client using the Model Context Protocol. This MCP Server lets you interact with Elasticsearch indices through natural language conversations, performing queries, exploring mappings, and viewing index details without writing raw queries.

How to use

Open your MCP Client and start a new conversation. The MCP Server connects to your Elasticsearch data and you can ask questions like which indices exist, what fields are available, or to run searches with your preferred criteria. You can request index mappings, list shards, or perform searches with highlighting and query explanations. Use the available MCP server capabilities to explore and analyze your data through natural language prompts.

How to install

Prerequisites you need before installation are an Elasticsearch instance, valid authentication credentials, Docker (or an OCI runtime), and an MCP Client such as Claude Desktop.

Option A: Using Docker

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch", "stdio"
      ],
      "env": {
        "ES_URL": "<your-elasticsearch-url>",
        "ES_API_KEY": "<your-api-key>"
      }
    }
  }
}

How to install

Option B: Using the Published NPM Package

Open your MCP Client 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>",
        "OTEL_LOG_LEVEL": "none"
      }
    }
  }
}

Start a Conversation

Open a new conversation in your MCP Client. The MCP server should connect automatically, and you can begin asking questions about your Elasticsearch data.

Configuration options

You must provide either an API key or both a username and password for authentication. The following environment variables are used to connect to Elasticsearch:

ES_URL — Your Elasticsearch instance URL (required)
ES_API_KEY — Elasticsearch API key for authentication (optional)
ES_USERNAME — Elasticsearch username for basic authentication (optional)
ES_PASSWORD — Elasticsearch password for basic authentication (optional)
ES_CA_CERT — Path to custom CA certificate for SSL/TLS (optional)
ES_SSL_SKIP_VERIFY — Set to 1 or true to skip SSL verification (optional)
ES_PATH_PREFIX — Path prefix for non-root Elasticsearch paths (optional)
ES_VERSION — Target Elasticsearch version, defaults to 9.x (optional)

Developing Locally

If you want to modify or extend the MCP Server locally, follow these 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: add a new MCP Server with the provided configuration and point to your local build

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.

Example Questions

Ask natural language questions like: What indices do I have in my Elasticsearch cluster? Show me the field mappings for a specific index. Find all orders over a certain amount from a given period.

How It Works

Your MCP Client analyzes your request to determine the required Elasticsearch operations. The MCP Server executes these actions (listing indices, fetching mappings, performing searches), and the client presents results in a user-friendly format.

Troubleshooting

Ensure your MCP configuration is correct and that the Elasticsearch URL is accessible from your machine. Verify credentials have the necessary permissions and if using SSL with a custom CA, confirm the certificate path is correct and readable. Review terminal output for error messages and consult logs for details.

Tools and Endpoints

The server supports listing indices, retrieving index mappings, performing searches, and inspecting shard information. Use these capabilities through your MCP Client to interact with Elasticsearch data.

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 including highlighting, profiling, and explanation

get_shards

Get shard information for all or specific indices