esmole

esmole-mcp

Elasticsearch 7.x and 8.x for AI agents that manage their own connections: add, edit and remove clusters through MCP tools at runtime, per project, hot-reloaded, through SSH.

esmole-mcp is a stdio MCP server for Elasticsearch. Tell your agent "connect to the logs cluster through bastion.example.com, readonly" and it calls add_connection. The connection lands in a per-project .esmole.json or in your global store, and both are re-read on every tool call, so a change made by the agent, by you in an editor, or by another session applies on the next call. No client config edits, no restarts.

• Elasticsearch 7.x and 8.x, any number of named clusters, API key or basic auth.
• SSH tunnels with password, key or agent auth; host keys verified against known_hosts or a pinned fingerprint.
• readonly connections limited to an allowlist of read endpoints, absolute request timeouts, a 10 MB response cap, and results capped at 40 KB so a big aggregation cannot flood the context.

Need PostgreSQL or MySQL? dbmole-mcp is the same design for SQL databases.

Demo

Install

Requires Node.js 22 or newer. The server needs no configuration to start; connections are added later.

Claude Code

claude mcp add esmole -- npx -y esmole-mcp

Add --scope user to enable it in every project. Or install it as a plugin (Claude Code 2.1.275 or later):

/plugin install esmole --marketplace ed-smartass/esmole-mcp

Codex

codex mcp add esmole -- npx -y esmole-mcp

or in ~/.codex/config.toml:

[mcp_servers.esmole]

command = "npx" args = ["-y", "esmole-mcp"]

Cursor

VS Code

Claude Desktop

Download esmole-mcp- .mcpb from the latest release and open it, or add the JSON below to claude_desktop_config.json. Claude Desktop does not start servers inside a project, so keep connections in the global store (the default scope).

Any other MCP client

{

"mcpServers": { "esmole": { "command": "npx", "args": ["-y", "esmole-mcp"] } } }

Docker

The image is built from source:

git clone https://github.com/ed-smartass/esmole-mcp.git && cd esmole-mcp

docker build -t esmole-mcp .

{

"mcpServers": { "esmole": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "esmole-store:/home/node/.config/esmole", "-v", "/abs/path/to/project:/work", "-v", "/home/me/.ssh/known_hosts:/home/node/.ssh/known_hosts:ro", "esmole-mcp" ] } } }

The container runs as node with cwd /work: mount a project there to use its .esmole.json, and the named volume keeps the global store. Mount known_hosts for SSH connections (or pin ssh.hostKey), and any private key you reference by privateKeyPath, at the path the connection names; for ssh.agent: true, forward the agent socket (-v "$SSH_AUTH_SOCK:/ssh-agent" -e SSH_AUTH_SOCK=/ssh-agent). To reach hosts that only your machine can reach, add --add-host=host.docker.internal:host-gateway (Linux) and use host.docker.internal. The image has no git, so the "not ignored by git" check always warns.

A 0.1 setup that still sets ESMOLE_CONNECTIONS, ESMOLE_CONFIG or --config starts fine: the server prints one line on stderr saying they are ignored. See the changelog.

Quick start

Ask the agent, for example:

Add a readonly elasticsearch connection logs to this project: https on 10.0.0.20, API key

VnVhQ2ZH…, through ssh as deploy@bastion.example.com with my ssh agent. Then show the five

biggest indices.

It calls add_connection with:

{

"name": "logs", "host": "10.0.0.20", "apiKey": "VnVhQ2ZH…", "readonly": true, "ssh": { "host": "bastion.example.com", "user": "deploy", "agent": true }, "scope": "project" }

then test_connection and es_list_indices. Credentials you type in chat pass through the model's context; for production secrets, write the entry into the file yourself.

Connections

Two layers

• Same name in both: the project entry wins. list_connections reports each connection's source (project or global) and, when it hides an entry of the same name in the other layer, shadows.
• Hot reload. Both files are re-read on every tool call. Edit a file mid-session and the next call uses the new settings; a changed connection gets a fresh client, the old one is closed.
• Project file discovery. Starting from the server's working directory (Claude Code and Codex start it in the project directory), esmole walks up to the filesystem root and uses the first .esmole.json it finds. In a linked git worktree with no file of its own, it falls back to the main checkout's .esmole.json, so every worktree of a repo shares one file.
• Both files are plain JSON with mode 0600, written atomically. Writes keep entries they cannot parse verbatim, and refuse to overwrite a file that is not valid JSON.

Managing connections with tools

• add_connection takes the connection fields plus scope: "global" (default) or "project". With project and no file yet, the file is created at the main checkout root (or the git root, or the working directory outside git). If git does not ignore it, the response warns you; add .esmole.json to .gitignore so credentials are not committed.
• add_connection fails when the name already exists in the target layer. The same name in the other layer is allowed; the response says which entry now shadows which.
• update_connection patches the connection where it lives (the winning layer). A null value removes an optional field. An ssh object is merged into the stored one field by field, so { "ssh": { "hostKey": "SHA256:..." } } keeps the stored SSH secrets.
• remove_connection deletes it from that layer and tells you if that uncovers a same-name entry in the other layer.
• Credentials are never echoed back: list_connections shows scheme, host, port, the auth kind, verifyTls, readonly, source and whether SSH is used.

Broken and invalid entries

• An entry that fails validation does not silently disappear: its name resolves to an error (connection 'x' in is invalid: ...) instead of falling through to a same-name entry in the global store, and list_connections lists it as invalid. A name defined twice in one file is an error too. remove_connection can delete an invalid entry.
• A file that exists but is unreadable, not JSON, or the wrong shape is reported in list_connections (brokenLayers). A broken project file blocks every connection; a broken global store blocks only names the project file does not define. A missing file is just empty.

Connection fields

Unknown fields are rejected. Authentication is required: an apiKey, or both user and password.

Example .esmole.json:

{

"connections": [ { "name": "local", "host": "localhost", "scheme": "http", "user": "elastic", "password": "changeme" }, { "name": "logs", "host": "10.0.0.20", "apiKey": "VnVhQ2ZHY0JDZGJrUW0t...", "readonly": true, "ssh": { "host": "bastion.example.com", "user": "deploy", "agent": true } } ] }

SSH tunnels

{ "host": "bastion.example.com", "user": "deploy", "privateKeyPath": "~/.ssh/id_ed25519" }

{ "host": "bastion.example.com", "user": "deploy", "password": "…" } { "host": "bastion.example.com", "port": 2222, "user": "deploy", "agent": true } { "host": "bastion.example.com", "user": "deploy", "agent": true, "hostKey": "SHA256:EXAMPLEexampleEXAMPLEexampleEXAMPLEexample1" }

Host keys are verified. With hostKey set, the bastion's key must match it (trailing = padding is accepted) and known_hosts is not consulted. Otherwise the key must match an entry for the host in ~/.ssh/known_hosts (host on port 22, [host]:port otherwise):

• Plain and hashed host names match. Wildcard patterns never match, and a line with a negated wildcard (!*.example.com) is ignored.
• A key listed under @revoked is rejected for every host, whatever the line's host pattern. @cert-authority lines and unknown markers are skipped.

There is no trust-on-first-use: an unknown key fails the connection with an error that shows the presented fingerprint. Check it against a trusted source, then either add the host to known_hosts or pin it:

ssh-keyscan -p 22 bastion.example.com 2>/dev/null | ssh-keygen -lf -

256 SHA256:EXAMPLEexampleEXAMPLEexampleEXAMPLEexample1 bastion.example.com (ED25519)

and ask the agent to