elastic · swallez · Jun 18, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 18, 2025
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,6 @@
 dist
 node_modules
 yarn.lock
+.env
+.idea
+.vscode
diff --git a/Dockerfile b/Dockerfile
@@ -1,9 +1,19 @@
+# Copyright Elasticsearch B.V. and contributors
+# SPDX-License-Identifier: Apache-2.0
 FROM cgr.dev/chainguard/wolfi-base:latest
 
 RUN apk --no-cache add nodejs npm
 
 WORKDIR /app
-COPY . ./
-RUN npm install && npm run build
 
-ENTRYPOINT ["npm", "start"]
+# Install dependencies (Docker build cache friendly)
+COPY package.json package-lock.json tsconfig.json ./
+RUN touch index.ts && npm install
+
+COPY *.ts run-docker.sh ./
+RUN npm run build
+
+# Future-proof the CLI and require the "stdio" argument
+ENV RUNNING_IN_CONTAINER="true"
+
+ENTRYPOINT ["./run-docker.sh"]
diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
 # Elasticsearch MCP Server
 
-[![smithery badge](https://smithery.ai/badge/@elastic/mcp-server-elasticsearch)](https://smithery.ai/server/@elastic/mcp-server-elasticsearch)
-
 This repository contains experimental features intended for research and evaluation and are not production-ready.
 
 Connect to your Elasticsearch data directly from any MCP Client (like Claude Desktop) using the Model Context Protocol (MCP).
@@ -23,6 +21,7 @@ This server connects agents to your Elasticsearch data using the Model Context P
 
 * An Elasticsearch instance
 * Elasticsearch authentication credentials (API key or username/password)
+* Docker (or an OCI runtime)
 * MCP Client (e.g. Claude Desktop)
 
 ## Demo
@@ -31,18 +30,36 @@ This server connects agents to your Elasticsearch data using the Model Context P
 
 ## Installation & Setup
 
-### Installing via Smithery
+### Using Docker
 
-To install Elasticsearch MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@elastic/mcp-server-elasticsearch):
+1. **Configure MCP Client**
+   * Open your MCP Client. See the [list of MCP Clients](https://modelcontextprotocol.io/clients), 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:
 
-```bash
-npx -y @smithery/cli install @elastic/mcp-server-elasticsearch --client claude
-```
+   ```json
+   {
+     "mcpServers": {
+       "elasticsearch-mcp-server": {
+         "command": "docker",
+         "args": [
+           "run", "--rm", "-i",
+           "-e", "ES_URL=<your-elasticsearch-url>",
+           "-e", "ES_API_KEY=<your-api-key>",
+           "docker.elastic.co/mcp/elasticsearch", "stdio"
+         ]
+       }
+     }
+   }
+   ```
 
-### Using the Published NPM Package
+2. **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
 
-> [!TIP]
-> The easiest way to use Elasticsearch MCP Server is through the published npm package.
+
+### Using the Published NPM Package
 
 1. **Configure MCP Client**
    * Open your MCP Client. See the [list of MCP Clients](https://modelcontextprotocol.io/clients), here we are configuring Claude Desktop.
@@ -59,8 +76,9 @@ npx -y @smithery/cli install @elastic/mcp-server-elasticsearch --client claude
            "@elastic/mcp-server-elasticsearch"
          ],
          "env": {
-           "ES_URL": "your-elasticsearch-url",
-           "ES_API_KEY": "your-api-key"
+           "ES_URL": "<your-elasticsearch-url>",
+           "ES_API_KEY": "<your-api-key>",
+           "OTEL_LOG_LEVEL": "none"
          }
        }
      }
@@ -79,16 +97,16 @@ The Elasticsearch MCP Server supports configuration options to connect to your E
 > [!NOTE]
 > 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 |
-| `ES_SSL_SKIP_VERIFY` | Set to '1' or 'true' to skip SSL certificate verification | No |
-| `ES_PATH_PREFIX` | Path prefix for Elasticsearch instance exposed at a non-root path | No |
-| `ES_VERSION` | Server assumes Elasticsearch 9.x. Set to `8` target Elasticsearch 8.x | No |
+| 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       |
+| `ES_SSL_SKIP_VERIFY` | Set to '1' or 'true' to skip SSL certificate verification             | No       |
+| `ES_PATH_PREFIX`     | Path prefix for Elasticsearch instance exposed at a non-root path     | No       |
+| `ES_VERSION`         | Server assumes Elasticsearch 9.x. Set to `8` target Elasticsearch 8.x | No       |
 
 ### Developing Locally
 
@@ -150,23 +168,6 @@ The Elasticsearch MCP Server supports configuration options to connect to your E
    🔍 MCP Inspector is up and running at http://localhost:5173 🚀
    ```
 
-#### Docker image
-
-A `Dockerfile` is available if you would like to build and run the server in a container. To build, run:
-
-```sh
-docker build -t mcp-server-elasticsearch .
-```
-
-And to run, rather than using the `npx` command above or a custom `node` or `npm` command, run:
-
-```sh
-docker run -i \
-  -e ES_URL=<url> \
-  -e ES_API_KEY=<key> \
-  mcp-server-elasticsearch
-```
-
 ## Contributing
 
 We welcome contributions from the community! For details on how to contribute, please see [Contributing Guidelines](/docs/CONTRIBUTING.md).

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -28,6 +28,14 @@ Please note that this project follows the [Elastic's Open Source Community Code
    npm run build
    ```
 
+To build the Docker image, run:
+
+```sh
+npm run build-docker-image
+```
+
+This builds a multi-architecture image for amd64 and arm64. If you don't have a configuration that allows multi-architecture builds, simply run `docker build -t mcp/elasticsearch` .
+
 ## Start Elasticsearch
 
 You can use either:

diff --git a/index.ts b/index.ts
@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 /*
  * Copyright Elasticsearch B.V. and contributors
  * SPDX-License-Identifier: Apache-2.0
@@ -502,6 +500,16 @@ const config: ElasticsearchConfig = {
 }
 
 async function main (): Promise<void> {
+  // If we're running in a container (see Dockerfile), future-proof the command-line
+  // by requiring the stdio protocol (http will come later)
+  if (process.env.RUNNING_IN_CONTAINER === "true") {
+    if (process.argv.length != 3 || process.argv[2] !== "stdio" ) {
+      console.log("Missing protocol argument.");
+      console.log("Usage: npm start stdio");
+      process.exit(1);
+    }
+  }
+
   const transport = new StdioServerTransport()
   const server = await createElasticsearchMcpServer(config)