Skip to content
Back to search

mcp-server-elasticsearch

> [!CAUTION] > This MCP server is deprecated and will only receive critical security updates going forward. > It has been superseded by the Elastic Agent Builder MCP endpoint, which is available in…

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/elastic/mcp-server-elasticsearch 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/elastic/mcp-server-elasticsearch'

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/elastic--mcp-server-elasticsearch/badge.svg)](/listings/elastic--mcp-server-elasticsearch)

HTML

<a href="/listings/elastic--mcp-server-elasticsearch"><img src="/api/listings/elastic--mcp-server-elasticsearch/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 · 272 lines

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

  1. # Elasticsearch MCP Server
  2. > [!CAUTION]
  3. > This MCP server is deprecated and will only receive critical security updates going forward.
  4. > It has been superseded by the [Elastic Agent Builder](https://ela.st/agent-builder-docs) [MCP endpoint](https://ela.st/agent-builder-mcp), which is available in Elastic 9.2.0+ and Elasticsearch Serverless projects.
  5. ## Use the Elasticsearch MCP Server for AI Agents
  6. The Elasticsearch MCP Server connects your AI agents to Elasticsearch data using the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP).
  7. It enables natural language interactions with your Elasticsearch indices, allowing agents to query, analyze, and retrieve data without custom APIs.
  8. Follow these steps to deploy and configure the Elasticsearch MCP Server container image from AWS Marketplace.
  9. ### Before you begin
  10. Before you start, ensure you have:
  11. - An Elasticsearch cluster (version 8.x or 9.x) accessible from your AWS environment
  12. - Elasticsearch authentication credentials:
  13. - An [API key](https://www.elastic.co/docs/deploy-manage/api-keys), or
  14. - A [username](https://www.elastic.co/docs/deploy-manage/users-roles) and password pair
  15. - Docker installed and running in your AWS environment (for example, on an EC2 instance or in a container service)
  16. - An MCP client configured (such as Claude Desktop, Cursor, VS Code, or another MCP-compatible tool)
  17. - Network connectivity between your deployment environment and your Elasticsearch cluster
  18. > [!NOTE]
  19. >
  20. > These instructions apply to Elasticsearch MCP Server 0.4.0 and later.
  21. > For versions 0.3.1 and earlier, refer to the [README for v0.3.1](https://github.com/elastic/mcp-server-elasticsearch/tree/v0.3.1).
  22. ### Deploy the Elasticsearch MCP Server
  23. The Elasticsearch MCP Server is provided as a Docker container image available from AWS Marketplace. You can run it using either the stdio protocol (for direct client connections) or the streamable-HTTP protocol (for web-based integrations).
  24. #### Choose a protocol
  25. The server supports two protocols:
  26. - [stdio](https://modelcontextprotocol.io/specification/latest/basic/transports#stdio): Direct communication between the MCP client and server. Use this when your client supports stdio and runs in the same environment.
  27. - [streamable-HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http): HTTP-based protocol recommended for web integrations, stateful sessions, and concurrent clients.
  28. > **Note:** Server-Sent Events (SSE) is deprecated. Use streamable-HTTP instead.
  29. ### Configure the stdio protocol
  30. Use the stdio protocol when your MCP client connects directly to the server process.
  31. #### Set environment variables for stdio mode
  32. Set the following environment variables:
  33. - `ES_URL`: The URL of your Elasticsearch cluster (for example, `https://your-cluster.es.amazonaws.com:9200`)
  34. - For authentication, use one of these options:
  35. - API key: Set `ES_API_KEY` to your Elasticsearch API key
  36. - Basic authentication: Set `ES_USERNAME` and `ES_PASSWORD` to your Elasticsearch credentials
  37. - (Optional) `ES_SSL_SKIP_VERIFY`: Set to `true` to skip SSL/TLS certificate verification when connecting to Elasticsearch. Only use this for development or testing environments.
  38. #### Run the container in stdio mode
  39. Start the MCP server in stdio mode:
  40. ```bash
  41. docker run -i --rm \
  42. -e ES_URL \
  43. -e ES_API_KEY \
  44. docker.elastic.co/mcp/elasticsearch \
  45. stdio
  46. ```
  47. #### Configure Claude Desktop
  48. Add this configuration to your Claude Desktop configuration file:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "elasticsearch-mcp-server": {
  53. "command": "docker",
  54. "args": [
  55. "run", "-i", "--rm",
  56. "-e", "ES_URL",
  57. "-e", "ES_API_KEY",
  58. "docker.elastic.co/mcp/elasticsearch",
  59. "stdio"
  60. ],
  61. "env": {
  62. "ES_URL": "<elasticsearch-cluster-url>",
  63. "ES_API_KEY": "<elasticsearch-API-key>"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. Replace `<elasticsearch-cluster-url>` with your Elasticsearch cluster URL and `<elasticsearch-API-key>` with your API key.
  70. ### Configure the streamable-HTTP protocol
  71. Use the streamable-HTTP protocol for web-based integrations or when you need to support multiple concurrent clients.
  72. #### Set environment variables for HTTP mode
  73. Set the same environment variables as the stdio protocol:
  74. - `ES_URL`: The URL of your Elasticsearch cluster
  75. - For authentication, use one of these options:
  76. - API key: Set `ES_API_KEY` to your Elasticsearch API key
  77. - Basic authentication: Set `ES_USERNAME` and `ES_PASSWORD` to your Elasticsearch credentials
  78. - (Optional) `ES_SSL_SKIP_VERIFY`: Set to `true` to skip SSL/TLS certificate verification
  79. #### Run the container in HTTP mode
  80. Start the MCP server in HTTP mode:
  81. ```bash
  82. docker run --rm \
  83. -e ES_URL \
  84. -e ES_API_KEY \
  85. -p 8080:8080 \
  86. docker.elastic.co/mcp/elasticsearch \
  87. http
  88. ```
  89. The streamable-HTTP endpoint is available at `http://<host>:8080/mcp`. A health check endpoint is available at `http://<host>:8080/ping`.
  90. #### Configure Claude Desktop with HTTP proxy
  91. If you're using Claude Desktop (free edition) which only supports the stdio protocol, use `mcp-proxy` to bridge stdio to streamable-HTTP:
  92. 1. Install `mcp-proxy`:
  93. ```bash
  94. uv tool install mcp-proxy
  95. ```
  96. For alternative installation options, refer to [mcp-proxy/README.md](https://github.com/sparfenyuk/mcp-proxy/blob/main/README.md).
  97. 2. Add this configuration to Claude Desktop:
  98. ```json
  99. {
  100. "mcpServers": {
  101. "elasticsearch-mcp-server": {
  102. "command": "/<home-directory>/.local/bin/mcp-proxy",
  103. "args": [
  104. "--transport=streamablehttp",
  105. "--header", "Authorization", "ApiKey <elasticsearch-API-key>",
  106. "http://<mcp-server-host>:<mcp-server-port>/mcp"
  107. ]
  108. }
  109. }
  110. }
  111. ```
  112. Replace `<home-directory>`, `<elasticsearch-API-key>`, `<mcp-server-host>`, and `<mcp-server-port>` with your values.
  113. ### Verify the connection
  114. After configuring your MCP client, verify the connection works:
  115. 1. Start your MCP client (for example, Claude Desktop or Cursor).
  116. 2. Check that the Elasticsearch MCP Server appears in your available MCP servers.
  117. 3. Test a simple query through your agent interface to confirm it can access your Elasticsearch indices.
  118. If the connection fails, verify:
  119. - Your Elasticsearch cluster URL is correct and accessible from your AWS environment
  120. - Your authentication credentials are valid and have the necessary permissions
  121. - Network connectivity exists between the container and your Elasticsearch cluster (check security groups and network ACLs)
  122. - Docker is running and the container started successfully (check container logs with `docker logs <container-id>`)
  123. ### Monitor health and status
  124. Monitor the health and proper function of the Elasticsearch MCP Server using these methods:
  125. #### Check container status
  126. Verify the container is running:
  127. ```bash
  128. docker ps | grep elasticsearch-mcp-server
  129. ```
  130. The container should appear in the list with a status of `Up`.
  131. #### Test the health endpoint (HTTP mode)
  132. If you're using the streamable-HTTP protocol, test the health check endpoint:
  133. ```bash
  134. curl http://<host>:8080/ping
  135. ```
  136. A successful response returns `pong`, indicating the server is running and healthy.
  137. #### Check container logs
  138. View container logs to identify any issues:
  139. ```bash
  140. docker logs <container-id>
  141. ```
  142. Look for error messages related to:
  143. - Elasticsearch connection failures
  144. - Authentication errors
  145. - Network connectivity issues
  146. #### Verify Elasticsearch connectivity
  147. Test connectivity to your Elasticsearch cluster from the container:
  148. ```bash
  149. docker exec <container-id> curl -k -u <username>:<password> <ES_URL>
  150. ```
  151. Or with an API key:
  152. ```bash
  153. docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>
  154. ```
  155. A successful response indicates the container can reach your Elasticsearch cluster.
  156. ### Security and sensitive information
  157. The Elasticsearch MCP Server handles authentication credentials securely:
  158. #### Credential storage
  159. - **API keys and passwords**: Stored only in environment variables passed to the container. They are not persisted to disk or logged.
  160. - **Environment variables**: Set when you run the container. Use AWS Secrets Manager or AWS Systems Manager Parameter Store to manage credentials securely in production environments.
  161. #### Data encryption
  162. - **In transit**: The MCP server communicates with Elasticsearch over HTTPS when your `ES_URL` uses the `https://` protocol. Ensure your Elasticsearch cluster has SSL/TLS enabled.
  163. - **At rest**: The container does not store data locally. All data remains in your Elasticsearch cluster, which uses your cluster's encryption settings.
  164. #### Best practices
  165. - Rotate API keys regularly (every 30-90 days for production environments)
  166. - Use API keys with minimal required permissions (read-only access to specific indices when possible)
  167. - Never commit credentials to version control or share them in logs
  168. - Use AWS Secrets Manager or Parameter Store to inject credentials at runtime instead of hardcoding them
  169. ### AWS service quotas
  170. The Elasticsearch MCP Server runs as a container in your AWS environment. Consider these AWS service quotas:
  171. - **EC2 instance limits**: If running on EC2, ensure your instance type supports your expected workload
  172. - **Elastic Container Service (ECS)**: If using ECS, review [ECS service quotas](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-quotas.html)
  173. - **Elastic Kubernetes Service (EKS)**: If using EKS, review [EKS service quotas](https://docs.aws.amazon.com/eks/latest/userguide/service-quotas.html)
  174. - **Network bandwidth**: Ensure sufficient network bandwidth between your container and Elasticsearch cluster
  175. To request quota increases, use the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/) or refer to the [AWS General Reference Guide](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html).
  176. ### Available tools
  177. Once connected, the MCP server provides these tools to your agent:
  178. - `list_indices`: List all available Elasticsearch indices
  179. - `get_mappings`: Get field mappings for a specific Elasticsearch index
  180. - `search`: Perform an Elasticsearch search using query DSL
  181. - `esql`: Execute an ES|QL query
  182. - `get_shards`: Get shard information for all or specific indices
  183. Your agent can use these tools to interact with your Elasticsearch data through natural language conversations.
  184. ### Next steps
  185. - Learn about AI-powered features available in the Elastic platform
  186. - Explore Agent Builder for building custom AI agents with Elasticsearch

Ratings and comments

Sign in to rate this skill.

Sign in

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