Skip to content

Commit 345b876

Browse files
swallezswallez
committed
Add installation documentation
1 parent 3aa8ee2 commit 345b876

File tree

1 file changed

+106
-10
lines changed

1 file changed

+106
-10
lines changed

‎README.md

Lines changed: 106 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
> [!CAUTION]
44
>
5-
> **WORK IN PROGRESS**. This is a development branch, not ready for use, things may be broken. You've been warned!
5+
> **WARNING: this is MCP server is EXPERIMENTAL.**
66
7-
Connect to your Elasticsearch data directly from any MCP Client (like Claude Desktop) using the Model Context Protocol (MCP).
7+
Connect to your Elasticsearch data directly from any MCP Client using the Model Context Protocol (MCP).
88

99
This server connects agents to your Elasticsearch data using the Model Context Protocol. It allows you to interact with your Elasticsearch indices through natural language conversations.
1010

@@ -20,16 +20,112 @@ This server connects agents to your Elasticsearch data using the Model Context P
2020

2121
* An Elasticsearch instance
2222
* Elasticsearch authentication credentials (API key or username/password)
23-
* MCP Client (e.g. Claude Desktop)
23+
* An MCP Client (e.g. [Claude Desktop](https://claude.ai/download), [Goose](https://block.github.io/goose/))
2424

2525
## Installation & Setup
2626

27-
This branch is a development branch. This version is not packaged yet.
27+
This MCP server is provided as a Docker image at `docker.elastic.co/mcp/elasticsearch`
28+
that supports MCP's stdio, SSE and streamable-HTTP protocols.
2829

29-
One-time operations:
30-
* make sure [Rust is installed](https://www.rust-lang.org/tools/install)
31-
* copy the `.env-example` file to `.env` and update its content according to your environment
30+
Running this container without any argument will output a usage message:
31+
32+
```
33+
docker run docker.elastic.co/mcp/elasticsearch
34+
```
35+
36+
```
37+
Usage: elasticsearch-mcp-server <COMMAND>
38+
39+
Commands:
40+
stdio Start a stdio server
41+
http Start a streamable-HTTP server with optional SSE support
42+
help Print this message or the help of the given subcommand(s)
43+
44+
Options:
45+
-h, --help Print help
46+
```
47+
48+
### Using the stdio protocol
49+
50+
The MCP server needs environment variables to be set:
51+
* `ES_URL`, the URL of your Elasticsearch cluster
52+
* `ES_API_KEY`, the Elasticsearch API key. We **strongly recommend** creating an API key
53+
with limited privileges so that the LLM only has access to the data and operations
54+
required for the usage context.
55+
* Optionally, `ES_SSL_SKIP_VERIFY` set to `true` skips SSL/TLS certificate verification when connecting
56+
to Elasticsearch. The ability to provide a custom certificate will be added in a later version.
57+
58+
The MCP server is started in stdio mode with this command:
59+
60+
```bash
61+
docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio
62+
```
63+
64+
The configuration for Claude Desktop is as follows:
65+
66+
```json
67+
{
68+
"mcpServers": {
69+
"elasticsearch-mcp-server": {
70+
"command": "docker",
71+
"args": [
72+
"run", "-i", "--rm",
73+
"-e", "ES_URL", "-e", "ES_API_KEY",
74+
"docker.elastic.co/mcp/elasticsearch",
75+
"stdio"
76+
],
77+
"env": {
78+
"ES_URL": "<elasticsearch-cluster-url>",
79+
"ES_API_KEY": "<elasticsearch-API-key>"
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
### Using the streamable-HTTP and SSE protocols
87+
88+
Note: streamable-HTTP is recommended, as [SSE is deprecated](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse-deprecated).
89+
90+
The MCP server needs environment variables to be set:
91+
* `ES_URL`, the URL of your Elasticsearch cluster
92+
* Optionally, `ES_SSL_SKIP_VERIFY` set to `true` skips SSL/TLS certificate verification when connecting
93+
to Elasticsearch. The ability to provide a custom certificate will be added in a later version.
94+
95+
The MCP client must also be configured with an `Authorization` header containing the Elasticsearch
96+
cluster's API key
97+
98+
The MCP server is started in http mode with this command:
99+
100+
```bash
101+
docker run --rm -e ES_URL -p 8080:8080 docker.elastic.co/mcp/elasticsearch http
102+
```
103+
104+
The streamable-HTTP endpoint is at `http:<host>:8080/mcp`
105+
106+
Configuration for Claude Desktop (free edition that only supports the stdio protocol).
107+
108+
1. Install `mcp-proxy` (or an equivalent), that will bridge stdio to streamable-http. The executable
109+
will be installed in `~/.local/bin`:
110+
111+
```bash
112+
uv tool install mcp-proxy
113+
```
114+
115+
2. Add this configuration to Claude Desktop:
116+
117+
```json
118+
{
119+
"mcpServers": {
120+
"elasticsearch-mcp-server": {
121+
"command": "/<home-directory>/.local/bin/mcp-proxy",
122+
"args": [
123+
"--transport=streamablehttp",
124+
"--header", "Authorization", "ApiKey <elasticsearch-API-key>",
125+
"http://<mcp-server-host>:<mcp-server-port>/mcp"
126+
]
127+
}
128+
}
129+
}
130+
```
32131

33-
And run
34-
* `cargo run http` for a streamable-http server on http://localhost:8080
35-
* `/path/to/scripts/cargo-run.sh stdio` for a stdio server (this script sets the current directory before starting `cargo run`)

0 commit comments

Comments
 (0)