Skip to content
Back to search

elasticsearch-mcp-server

A Model Context Protocol (MCP) server implementation that provides Elasticsearch and OpenSearch interaction.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cr7258/elasticsearch-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cr7258/elasticsearch-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cr7258--elasticsearch-mcp-server/badge.svg)](/listings/cr7258--elasticsearch-mcp-server)

HTML

<a href="/listings/cr7258--elasticsearch-mcp-server"><img src="/api/listings/cr7258--elasticsearch-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 452 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Elasticsearch/OpenSearch MCP Server
  2. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/cr7258-elasticsearch-mcp-server-badge.png)](https://mseep.ai/app/cr7258-elasticsearch-mcp-server)
  3. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/cr7258/elasticsearch-mcp-server)](https://archestra.ai/mcp-catalog/cr7258__elasticsearch-mcp-server)
  4. ## Overview
  5. A 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.
  6. <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>
  7. ## Demo
  8. https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
  9. ## Features
  10. ### General Operations
  11. - `general_api_request`: Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
  12. ### Index Operations
  13. - `list_indices`: List all indices.
  14. - `get_index`: Returns information (mappings, settings, aliases) about one or more indices.
  15. - `create_index`: Create a new index.
  16. - `delete_index`: Delete an index.
  17. - `create_data_stream`: Create a new data stream (requires matching index template).
  18. - `get_data_stream`: Get information about one or more data streams.
  19. - `delete_data_stream`: Delete one or more data streams and their backing indices.
  20. ### Document Operations
  21. - `search_documents`: Search for documents.
  22. - `index_document`: Creates or updates a document in the index.
  23. - `get_document`: Get a document by ID.
  24. - `delete_document`: Delete a document by ID.
  25. - `delete_by_query`: Deletes documents matching the provided query.
  26. ### Cluster Operations
  27. - `get_cluster_health`: Returns basic information about the health of the cluster.
  28. - `get_cluster_stats`: Returns high-level overview of cluster statistics.
  29. ### Alias Operations
  30. - `list_aliases`: List all aliases.
  31. - `get_alias`: Get alias information for a specific index.
  32. - `put_alias`: Create or update an alias for a specific index.
  33. - `delete_alias`: Delete an alias for a specific index.
  34. ### Analyzer Operations
  35. - `analyze_text`: Analyze text using a specified analyzer or custom analysis chain. Useful for debugging search queries and understanding how text is tokenized.
  36. ## Configure Environment Variables
  37. The MCP server supports the following environment variables:
  38. ### Basic Authentication (Username/Password)
  39. - `ELASTICSEARCH_USERNAME`: Username for basic authentication
  40. - `ELASTICSEARCH_PASSWORD`: Password for basic authentication
  41. - `OPENSEARCH_USERNAME`: Username for OpenSearch basic authentication
  42. - `OPENSEARCH_PASSWORD`: Password for OpenSearch basic authentication
  43. ### API Key Authentication (Elasticsearch only) - Recommended
  44. - `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.
  45. ### Connection Settings
  46. - `ELASTICSEARCH_HOSTS` / `OPENSEARCH_HOSTS`: Comma-separated list of hosts (default: `https://localhost:9200`)
  47. - `ELASTICSEARCH_CLUSTERS` / `OPENSEARCH_CLUSTERS`: Inline JSON object for named cluster configurations. When set, tools can target a specific cluster with the optional `cluster` parameter.
  48. - `ELASTICSEARCH_CLUSTERS_FILE` / `OPENSEARCH_CLUSTERS_FILE`: Path to a JSON file with the clusters object. Recommended when the configuration is embedded inside another JSON file (e.g. the MCP client config) because it avoids JSON-in-JSON escaping. Takes precedence over the inline variable when both are set.
  49. - `DEFAULT_CLUSTER`: Default cluster name to use when multi-cluster configuration is set and a tool call omits `cluster` (defaults to the first configured cluster).
  50. - `VERIFY_CERTS`: Whether to verify SSL certificates (default: `false`)
  51. - `REQUEST_TIMEOUT`: Request timeout in seconds (optional, uses client default if not set)
  52. - `ELASTICSEARCH_PROXY` / `OPENSEARCH_PROXY`: Route all requests through a proxy (optional). Supported schemes are `http://`, `https://`, `socks5://` and `socks5h://`, e.g. `socks5h://127.0.0.1:1080` for an SSH dynamic port forward (`ssh -D 1080 bastion`). Use `socks5h` when the cluster host name only resolves on the proxy side. In a multi-cluster configuration, set `proxy` per cluster; it overrides the environment variable.
  53. ### Multiple Cluster Configuration
  54. By default, the server uses a single Elasticsearch cluster from `ELASTICSEARCH_HOSTS`, `ELASTICSEARCH_USERNAME`, `ELASTICSEARCH_PASSWORD`, and `ELASTICSEARCH_API_KEY`, or a single OpenSearch cluster from `OPENSEARCH_HOSTS`, `OPENSEARCH_USERNAME`, and `OPENSEARCH_PASSWORD`. To configure multiple named clusters, set `ELASTICSEARCH_CLUSTERS` (or `OPENSEARCH_CLUSTERS`) to a JSON object inside the MCP server configuration. Because the value is a JSON string embedded in another JSON file, the inner quotes need to be escaped:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "elasticsearch-mcp-server": {
  59. "command": "uvx",
  60. "args": [
  61. "elasticsearch-mcp-server"
  62. ],
  63. "env": {
  64. "ELASTICSEARCH_CLUSTERS": "{\"prod\": {\"hosts\": [\"https://prod-es:9200\"], \"api_key\": \"<PROD_API_KEY>\", \"verify_certs\": true}, \"staging\": {\"hosts\": [\"https://staging-es:9200\"], \"username\": \"elastic\", \"password\": \"<STAGING_PASSWORD>\"}}",
  65. "DEFAULT_CLUSTER": "prod"
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. For better readability, point `ELASTICSEARCH_CLUSTERS_FILE` (or `OPENSEARCH_CLUSTERS_FILE`) at a standalone JSON file instead. The value is just a path so it avoids the JSON-in-JSON escaping:
  72. ```json
  73. {
  74. "mcpServers": {
  75. "elasticsearch-mcp-server": {
  76. "command": "uvx",
  77. "args": [
  78. "elasticsearch-mcp-server"
  79. ],
  80. "env": {
  81. "ELASTICSEARCH_CLUSTERS_FILE": "/etc/mcp/es-clusters.json",
  82. "DEFAULT_CLUSTER": "prod"
  83. }
  84. }
  85. }
  86. }
  87. ```
  88. `/etc/mcp/es-clusters.json`:
  89. ```json
  90. {
  91. "prod": {
  92. "hosts": ["https://prod-es:9200"],
  93. "api_key": "<PROD_API_KEY>",
  94. "verify_certs": true
  95. },
  96. "staging": {
  97. "hosts": ["https://staging-es:9200"],
  98. "username": "elastic",
  99. "password": "<STAGING_PASSWORD>",
  100. "proxy": "socks5h://127.0.0.1:1080"
  101. }
  102. }
  103. ```
  104. Here only `staging` is reached through a SOCKS proxy, `prod` connects directly.
  105. Every tool accepts an optional `cluster` parameter. If omitted, the server uses `DEFAULT_CLUSTER`. When `DEFAULT_CLUSTER` is not set, the first cluster in the JSON object is used as the default. A tool call targeting a specific cluster looks like:
  106. ```json
  107. {
  108. "cluster": "staging",
  109. "index": "logs-*",
  110. "body": {
  111. "query": {
  112. "match_all": {}
  113. }
  114. }
  115. }
  116. ```
  117. ### MCP Server Authentication (HTTP Transports Only)
  118. When 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.
  119. - `MCP_API_KEY`: API key for MCP server authentication. Clients must include `Authorization: Bearer <MCP_API_KEY>` header.
  120. **Important Security Notes:**
  121. - Authentication is **only applicable** for HTTP transports (`sse`, `streamable-http`). The `stdio` transport uses local process communication and doesn't require authentication.
  122. - 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.
  123. - For production deployments with HTTP transports, **always set `MCP_API_KEY`**.
  124. ```bash
  125. # Generate a secure API key (example using openssl)
  126. export MCP_API_KEY=$(openssl rand -base64 32)
  127. # Or set a custom API key
  128. export MCP_API_KEY="your-secure-api-key-here"
  129. ```
  130. ### Disable High-Risk Operations
  131. - `DISABLE_HIGH_RISK_OPERATIONS`: Set to `true` to disable all write operations (default: `false`)
  132. - `DISABLE_OPERATIONS`: Comma-separated list of specific operations to disable (optional, uses default write operations list if not set)
  133. When `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.
  134. - **Index Operations:**
  135. - `create_index`
  136. - `delete_index`
  137. - **Document Operations:**
  138. - `index_document`
  139. - `delete_document`
  140. - `delete_by_query`
  141. - **Data Stream Operations:**
  142. - `create_data_stream`
  143. - `delete_data_stream`
  144. - **Alias Operations:**
  145. - `put_alias`
  146. - `delete_alias`
  147. - **General API Operations:**
  148. - `general_api_request`
  149. Optionally, you can specify a comma-separated list of operations to disable in the `DISABLE_OPERATIONS` environment variable.
  150. ```bash
  151. # Disable High-Risk Operations
  152. export DISABLE_HIGH_RISK_OPERATIONS=true
  153. # Disable specific operations only
  154. export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"
  155. ```
  156. ### GCF Response Encoding (optional)
  157. Opt in to serialize tool-result payloads as [GCF](https://gcformat.com/) (Graph Compact Format), a token-optimized wire format, in the content block the model reads. Elasticsearch returns large, uniform record sets (search hits, aggregation buckets, mappings), the shape GCF compacts best: on representative responses it is **~39% fewer tokens than compact JSON** (40% on search hits), losslessly.
  158. ```bash
  159. export RESPONSE_FORMAT=gcf
  160. ```
  161. `structuredContent` is preserved unchanged, so a tool's declared output schema still validates and any non-model client keeps receiving JSON; only the model-facing text block is re-encoded. Encoding is fail-safe: any error, including a value outside GCF's canonical `int64` numeric domain (which GCF rejects rather than silently approximating), leaves the original JSON result untouched, so a tool call is never dropped over encoding. Default behavior is unchanged when `RESPONSE_FORMAT` is unset.
  162. Reproduce the token comparison: `uv run --with tiktoken python benchmarks/gcf_benchmark.py`.
  163. ## Start Elasticsearch/OpenSearch Cluster
  164. Start the Elasticsearch/OpenSearch cluster using Docker Compose:
  165. ```bash
  166. # For Elasticsearch
  167. docker-compose -f docker-compose-elasticsearch.yml up -d
  168. # For OpenSearch
  169. docker-compose -f docker-compose-opensearch.yml up -d
  170. ```
  171. The default Elasticsearch username is `elastic` and password is `test123`. The default OpenSearch username is `admin` and password is `admin`.
  172. You can access Kibana/OpenSearch Dashboards from http://localhost:5601.
  173. ## Stdio
  174. ### Option 1: Using uvx
  175. Using `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`.
  176. ```json
  177. // For Elasticsearch with username/password
  178. {
  179. "mcpServers": {
  180. "elasticsearch-mcp-server": {
  181. "command": "uvx",
  182. "args": [
  183. "elasticsearch-mcp-server"
  184. ],
  185. "env": {
  186. "ELASTICSEARCH_HOSTS": "https://localhost:9200",
  187. "ELASTICSEARCH_USERNAME": "elastic",
  188. "ELASTICSEARCH_PASSWORD": "test123"
  189. }
  190. }
  191. }
  192. }
  193. // For Elasticsearch with API key
  194. {
  195. "mcpServers": {
  196. "elasticsearch-mcp-server": {
  197. "command": "uvx",
  198. "args": [
  199. "elasticsearch-mcp-server"
  200. ],
  201. "env": {
  202. "ELASTICSEARCH_HOSTS": "https://localhost:9200",
  203. "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
  204. }
  205. }
  206. }
  207. }
  208. // For OpenSearch
  209. {
  210. "mcpServers": {
  211. "opensearch-mcp-server": {
  212. "command": "uvx",
  213. "args": [
  214. "opensearch-mcp-server"
  215. ],
  216. "env": {
  217. "OPENSEARCH_HOSTS": "https://localhost:9200",
  218. "OPENSEARCH_USERNAME": "admin",
  219. "OPENSEARCH_PASSWORD": "admin"
  220. }
  221. }
  222. }
  223. }
  224. ```
  225. ### Option 2: Using uv with local development
  226. Using `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`.
  227. ```json
  228. // For Elasticsearch with username/password
  229. {
  230. "mcpServers": {
  231. "elasticsearch-mcp-server": {
  232. "command": "uv",
  233. "args": [
  234. "--directory",
  235. "path/to/elasticsearch-mcp-server",
  236. "run",
  237. "elasticsearch-mcp-server"
  238. ],
  239. "env": {
  240. "ELASTICSEARCH_HOSTS": "https://localhost:9200",
  241. "ELASTICSEARCH_USERNAME": "elastic",
  242. "ELASTICSEARCH_PASSWORD": "test123"
  243. }
  244. }
  245. }
  246. }
  247. // For Elasticsearch with API key
  248. {
  249. "mcpServers": {
  250. "elasticsearch-mcp-server": {
  251. "command": "uv",
  252. "args": [
  253. "--directory",
  254. "path/to/elasticsearch-mcp-server",
  255. "run",
  256. "elasticsearch-mcp-server"
  257. ],
  258. "env": {
  259. "ELASTICSEARCH_HOSTS": "https://localhost:9200",
  260. "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
  261. }
  262. }
  263. }
  264. }
  265. // For OpenSearch
  266. {
  267. "mcpServers": {
  268. "opensearch-mcp-server": {
  269. "command": "uv",
  270. "args": [
  271. "--directory",
  272. "path/to/elasticsearch-mcp-server",
  273. "run",
  274. "opensearch-mcp-server"
  275. ],
  276. "env": {
  277. "OPENSEARCH_HOSTS": "https://localhost:9200",
  278. "OPENSEARCH_USERNAME": "admin",
  279. "OPENSEARCH_PASSWORD": "admin"
  280. }
  281. }
  282. }
  283. }
  284. ```
  285. ## SSE
  286. ### Option 1: Using uvx
  287. ```bash
  288. # export environment variables (with username/password)
  289. export ELASTICSEARCH_HOSTS="https://localhost:9200"
  290. export ELASTICSEARCH_USERNAME="elastic"
  291. export ELASTICSEARCH_PASSWORD="test123"
  292. # OR export environment variables (with API key)
  293. export ELASTICSEARCH_HOSTS="https://localhost:9200"
  294. export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
  295. # By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
  296. uvx elasticsearch-mcp-server --transport sse
  297. # The host, port, and path can be specified using the --host, --port, and --path options
  298. uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse
  299. ```
  300. ### Option 2: Using uv
  301. ```bash
  302. # By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
  303. uv run src/server.py elasticsearch-mcp-server --transport sse
  304. # The host, port, and path can be specified using the --host, --port, and --path options
  305. uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse
  306. ```
  307. ## Streamable HTTP
  308. ### Option 1: Using uvx
  309. ```bash
  310. # export environment variables (with username/password)
  311. export ELASTICSEARCH_HOSTS="https://localhost:9200"
  312. export ELASTICSEARCH_USERNAME="elastic"
  313. export ELASTICSEARCH_PASSWORD="test123"
  314. # OR export environment variables (with API key)
  315. export ELASTICSEARCH_HOSTS="https://localhost:9200"
  316. export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
  317. # By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
  318. uvx elasticsearch-mcp-server --transport streamable-http
  319. # The host, port, and path can be specified using the --host, --port, and --path options
  320. uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
  321. ```
  322. ### Option 2: Using uv
  323. ```bash
  324. # By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
  325. uv run src/server.py elasticsearch-mcp-server --transport streamable-http
  326. # The host, port, and path can be specified using the --host, --port, and --path options
  327. uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
  328. ```
  329. ## Compatibility
  330. The 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).
  331. | MCP Server | Elasticsearch |
  332. | --- | --- |
  333. | elasticsearch-mcp-server-es7 | Elasticsearch 7.x |
  334. | elasticsearch-mcp-server | Elasticsearch 8.x |
  335. | elasticsearch-mcp-server-es9 | Elasticsearch 9.x |
  336. | opensearch-mcp-server | OpenSearch 1.x, 2.x, 3.x |
  337. 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:
  338. ```bash
  339. uvx elasticsearch-mcp-server-es7
  340. ```
  341. If 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:
  342. ```bash
  343. uv run src/server.py elasticsearch-mcp-server
  344. ```
  345. ## Kubernetes Deployment
  346. The Docker image is published to `ghcr.io/cr7258/elasticsearch-mcp-server` and the Helm chart is available as an OCI artifact at `oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server` repository.
  347. For full installation instructions, configuration reference, and usage examples see the **[Helm chart README](helm/elasticsearch-mcp-server/README.md)**.
  348. ## License
  349. This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.