Elasticsearch/OpenSearch MCP Server

1 
2<!-- mcp-name: io.github.cr7258/elasticsearch-mcp-server -->
3 
4# Elasticsearch/OpenSearch MCP Server
5 
6[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/cr7258-elasticsearch-mcp-server-badge.png)](https://mseep.ai/app/cr7258-elasticsearch-mcp-server)
7 
8[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/cr7258/elasticsearch-mcp-server)](https://archestra.ai/mcp-catalog/cr7258__elasticsearch-mcp-server)
9 
10[MCP Official Registry]( https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cr7258/elasticsearch-mcp-server)
11 
12## Overview
13 
14A Model Context Protocol (MCP) server implementation that provides Elasticsearch and OpenSearch interaction. This server enables searching documents, analyzing indices, and managing cluster through a set of tools.
15 
16<a href="https://glama.ai/mcp/servers/b3po3delex"><img width="380" height="200" src="https://glama.ai/mcp/servers/b3po3delex/badge" alt="Elasticsearch MCP Server" /></a>
17 
18## Demo
19 
20https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
21 
22## Features
23 
24### General Operations
25 
26- `general_api_request`: Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
27 
28### Index Operations
29 
30- `list_indices`: List all indices.
31- `get_index`: Returns information (mappings, settings, aliases) about one or more indices.
32- `create_index`: Create a new index.
33- `delete_index`: Delete an index.
34- `create_data_stream`: Create a new data stream (requires matching index template).
35- `get_data_stream`: Get information about one or more data streams.
36- `delete_data_stream`: Delete one or more data streams and their backing indices.
37 
38### Document Operations
39 
40- `search_documents`: Search for documents.
41- `index_document`: Creates or updates a document in the index.
42- `get_document`: Get a document by ID.
43- `delete_document`: Delete a document by ID.
44- `delete_by_query`: Deletes documents matching the provided query.
45 
46### Cluster Operations
47 
48- `get_cluster_health`: Returns basic information about the health of the cluster.
49- `get_cluster_stats`: Returns high-level overview of cluster statistics.
50 
51### Alias Operations
52 
53- `list_aliases`: List all aliases.
54- `get_alias`: Get alias information for a specific index.
55- `put_alias`: Create or update an alias for a specific index.
56- `delete_alias`: Delete an alias for a specific index.
57 
58### Analyzer Operations
59 
60- `analyze_text`: Analyze text using a specified analyzer or custom analysis chain. Useful for debugging search queries and understanding how text is tokenized.
61 
62## Configure Environment Variables
63 
64The MCP server supports the following environment variables:
65 
66### Basic Authentication (Username/Password)
67- `ELASTICSEARCH_USERNAME`: Username for basic authentication
68- `ELASTICSEARCH_PASSWORD`: Password for basic authentication
69- `OPENSEARCH_USERNAME`: Username for OpenSearch basic authentication
70- `OPENSEARCH_PASSWORD`: Password for OpenSearch basic authentication
71 
72### API Key Authentication (Elasticsearch only) - Recommended
73- `ELASTICSEARCH_API_KEY`: API key for [Elasticsearch](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys) or [Elastic Cloud](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys) Authentication.
74 
75### Connection Settings
76- `ELASTICSEARCH_HOSTS` / `OPENSEARCH_HOSTS`: Comma-separated list of hosts (default: `https://localhost:9200`)
77- `VERIFY_CERTS`: Whether to verify SSL certificates (default: `false`)
78- `REQUEST_TIMEOUT`: Request timeout in seconds (optional, uses client default if not set)
79 
80### MCP Server Authentication (HTTP Transports Only)
81 
82When running the MCP server with HTTP-based transports (SSE or Streamable HTTP), you can enable Bearer token authentication to protect the server from unauthorized access.
83 
84- `MCP_API_KEY`: API key for MCP server authentication. Clients must include `Authorization: Bearer <MCP_API_KEY>` header.
85 
86**Important Security Notes:**
87- Authentication is **only applicable** for HTTP transports (`sse`, `streamable-http`). The `stdio` transport uses local process communication and doesn't require authentication.
88- If `MCP_API_KEY` is **not set**, the MCP server will be accessible **without authentication**. This is a security risk when exposing the server over a network.
89- For production deployments with HTTP transports, **always set `MCP_API_KEY`**.
90 
91```bash
92# Generate a secure API key (example using openssl)
93export MCP_API_KEY=$(openssl rand -base64 32)
94 
95# Or set a custom API key
96export MCP_API_KEY="your-secure-api-key-here"
97```
98 
99### Disable High-Risk Operations
100 
101- `DISABLE_HIGH_RISK_OPERATIONS`: Set to `true` to disable all write operations (default: `false`)
102- `DISABLE_OPERATIONS`: Comma-separated list of specific operations to disable (optional, uses default write operations list if not set)
103 
104When `DISABLE_HIGH_RISK_OPERATIONS` is set to true, all MCP tools that perform write operations are completely hidden from the MCP client. In this mode, the following MCP tools are disabled by default.
105 
106- **Index Operations:**
107  - `create_index`
108  - `delete_index`
109  
110- **Document Operations:**
111  - `index_document`
112  - `delete_document`
113  - `delete_by_query`
114  
115- **Data Stream Operations:**
116  - `create_data_stream`
117  - `delete_data_stream`
118  
119- **Alias Operations:**
120  - `put_alias`
121  - `delete_alias`
122  
123- **General API Operations:**
124  - `general_api_request`
125 
126Optionally, you can specify a comma-separated list of operations to disable in the `DISABLE_OPERATIONS` environment variable.
127 
128```bash
129# Disable High-Risk Operations
130export DISABLE_HIGH_RISK_OPERATIONS=true
131# Disable specific operations only
132export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"
133```
134 
135## Start Elasticsearch/OpenSearch Cluster
136 
137Start the Elasticsearch/OpenSearch cluster using Docker Compose:
138 
139```bash
140# For Elasticsearch
141docker-compose -f docker-compose-elasticsearch.yml up -d
142 
143# For OpenSearch
144docker-compose -f docker-compose-opensearch.yml up -d
145```
146 
147The default Elasticsearch username is `elastic` and password is `test123`. The default OpenSearch username is `admin` and password is `admin`.
148 
149You can access Kibana/OpenSearch Dashboards from http://localhost:5601.
150 
151## Stdio
152 
153### Option 1: Using uvx
154 
155Using `uvx` will automatically install the package from PyPI, no need to clone the repository locally. Add the following configuration to 's config file `claude_desktop_config.json`.
156 
157```json
158// For Elasticsearch with username/password
159{
160  "mcpServers": {
161    "elasticsearch-mcp-server": {
162      "command": "uvx",
163      "args": [
164        "elasticsearch-mcp-server"
165      ],
166      "env": {
167        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
168        "ELASTICSEARCH_USERNAME": "elastic",
169        "ELASTICSEARCH_PASSWORD": "test123"
170      }
171    }
172  }
173}
174 
175// For Elasticsearch with API key
176{
177  "mcpServers": {
178    "elasticsearch-mcp-server": {
179      "command": "uvx",
180      "args": [
181        "elasticsearch-mcp-server"
182      ],
183      "env": {
184        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
185        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
186      }
187    }
188  }
189}
190 
191// For OpenSearch
192{
193  "mcpServers": {
194    "opensearch-mcp-server": {
195      "command": "uvx",
196      "args": [
197        "opensearch-mcp-server"
198      ],
199      "env": {
200        "OPENSEARCH_HOSTS": "https://localhost:9200",
201        "OPENSEARCH_USERNAME": "admin",
202        "OPENSEARCH_PASSWORD": "admin"
203      }
204    }
205  }
206}
207```
208 
209### Option 2: Using uv with local development
210 
211Using `uv` requires cloning the repository locally and specifying the path to the source code. Add the following configuration to Claude Desktop's config file `claude_desktop_config.json`.
212 
213```json
214// For Elasticsearch with username/password
215{
216  "mcpServers": {
217    "elasticsearch-mcp-server": {
218      "command": "uv",
219      "args": [
220        "--directory",
221        "path/to/elasticsearch-mcp-server",
222        "run",
223        "elasticsearch-mcp-server"
224      ],
225      "env": {
226        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
227        "ELASTICSEARCH_USERNAME": "elastic",
228        "ELASTICSEARCH_PASSWORD": "test123"
229      }
230    }
231  }
232}
233 
234// For Elasticsearch with API key
235{
236  "mcpServers": {
237    "elasticsearch-mcp-server": {
238      "command": "uv",
239      "args": [
240        "--directory",
241        "path/to/elasticsearch-mcp-server",
242        "run",
243        "elasticsearch-mcp-server"
244      ],
245      "env": {
246        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
247        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
248      }
249    }
250  }
251}
252 
253// For OpenSearch
254{
255  "mcpServers": {
256    "opensearch-mcp-server": {
257      "command": "uv",
258      "args": [
259        "--directory",
260        "path/to/elasticsearch-mcp-server",
261        "run",
262        "opensearch-mcp-server"
263      ],
264      "env": {
265        "OPENSEARCH_HOSTS": "https://localhost:9200",
266        "OPENSEARCH_USERNAME": "admin",
267        "OPENSEARCH_PASSWORD": "admin"
268      }
269    }
270  }
271}
272```
273 
274## SSE
275 
276### Option 1: Using uvx
277 
278```bash
279# export environment variables (with username/password)
280export ELASTICSEARCH_HOSTS="https://localhost:9200"
281export ELASTICSEARCH_USERNAME="elastic"
282export ELASTICSEARCH_PASSWORD="test123"
283 
284# OR export environment variables (with API key)
285export ELASTICSEARCH_HOSTS="https://localhost:9200"
286export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
287 
288# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
289uvx elasticsearch-mcp-server --transport sse
290 
291# The host, port, and path can be specified using the --host, --port, and --path options
292uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse
293```
294 
295### Option 2: Using uv
296 
297```bash
298# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
299uv run src/server.py elasticsearch-mcp-server --transport sse
300 
301# The host, port, and path can be specified using the --host, --port, and --path options
302uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse
303```
304 
305## Streamable HTTP
306 
307### Option 1: Using uvx
308 
309```bash
310# export environment variables (with username/password)
311export ELASTICSEARCH_HOSTS="https://localhost:9200"
312export ELASTICSEARCH_USERNAME="elastic"
313export ELASTICSEARCH_PASSWORD="test123"
314 
315# OR export environment variables (with API key)
316export ELASTICSEARCH_HOSTS="https://localhost:9200"
317export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
318 
319# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
320uvx elasticsearch-mcp-server --transport streamable-http
321 
322# The host, port, and path can be specified using the --host, --port, and --path options
323uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
324```
325 
326### Option 2: Using uv
327 
328```bash
329# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
330uv run src/server.py elasticsearch-mcp-server --transport streamable-http
331 
332# The host, port, and path can be specified using the --host, --port, and --path options
333uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
334```
335 
336## Compatibility
337 
338The MCP server is compatible with Elasticsearch 7.x, 8.x, and 9.x. By default, it uses the Elasticsearch 8.x client (without a suffix).
339 
340| MCP Server | Elasticsearch |
341| --- | --- |
342| elasticsearch-mcp-server-es7 | Elasticsearch 7.x |
343| elasticsearch-mcp-server | Elasticsearch 8.x |
344| elasticsearch-mcp-server-es9 | Elasticsearch 9.x |
345| opensearch-mcp-server | OpenSearch 1.x, 2.x, 3.x |
346 
347 To use the Elasticsearch 7.x client, run the `elasticsearch-mcp-server-es7` variant. For Elasticsearch 9.x, use `elasticsearch-mcp-server-es9`. For example:
348 
349```bash
350uvx elasticsearch-mcp-server-es7
351```
352 
353If you want to run different Elasticsearch variants (e.g., 7.x or 9.x) locally, simply update the `elasticsearch` dependency version in `pyproject.toml`, then start the server with:
354 
355```bash
356uv run src/server.py elasticsearch-mcp-server
357```
358 
359## License
360 
361This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details.
362