Elasticsearch MCP Server

Query Elasticsearch logs directly from Claude Cowork — with or without an SSH tunnel.

Installation

1. Install the plugin

Get es-mcp from the Cowork plugin marketplace and install it.

2. Install uv

The MCP server runs via uvx, which requires uv to be installed on your machine:

# Windows
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

3. Add the MCP entry to claude_desktop_config.json

Open the file at:

Windows:  %APPDATA%\Claude\claude_desktop_config.json
macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json

Add this minimal entry inside "mcpServers": { }:

{
  "mcpServers": {
    "elasticsearch-logs": {
      "command": "uvx",
      "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"]
    }
  }
}

That's it — no env vars needed.

4. Configure your profiles by asking Claude

Restart Cowork, then just ask Claude to add your Elasticsearch connections:

"Add a tealive_production profile — bastion is 43.216.208.205, pem is at ~/keys/prod.pem"

Claude will call configure_profile and save your settings to ~/.es-mcp/profiles.json automatically. You can add as many profiles as you like this way.

5. Restart Cowork

The SSH tunnel starts automatically on first tool use.

How profiles are stored

Profiles are saved to ~/.es-mcp/profiles.json — a plain, human-readable JSON file you can also edit directly if you prefer:

{
  "default": "tealive_production",
  "profiles": {
    "tealive_production": {
      "es_use_ssl": true,
      "es_verify_certs": false,
      "es_username": "your-username",
      "es_password": "your-password",
      "ssh_host": "43.216.208.205",
      "ssh_username": "ubuntu",
      "ssh_pem_file": "~/keys/prod.pem"
    },
    "baskbear": {
      "es_use_ssl": true,
      "es_verify_certs": false,
      "ssh_host": "baskbear-bastion-ip",
      "ssh_username": "ubuntu",
      "ssh_pem_file": "~/keys/baskbear.pem"
    }
  }
}

Config priority order

The server looks for profiles in this order — the first match wins:

1. ES_PROFILES env var (JSON string) — backward compat for existing users
2. ES_PROFILES_FILE env var — path to a custom JSON file
3. ~/.es-mcp/profiles.json — auto-discovered (written by configure_profile)
4. Legacy flat ES_* / SSH_* env vars — single profile named "default"

Selecting a profile

Every tool accepts an optional profile argument. Just ask naturally:

"Search baskbear logs for payment errors" "Show recent errors in tealive production"

Omit it and the default profile is used. Call list_profiles to see what's configured, or connection_info to inspect a specific one.

Per-profile settings reference

Tunnel resilience

SSH tunnels are kept alive with periodic keepalive packets (ssh_keepalive, 30s by default) so the server's idle timeout doesn't drop them. If a tunnel is dropped anyway, it is detected and automatically rebuilt on the next query — no need to restart Claude.

Available tools

All tools accept an optional profile argument to choose the Elasticsearch source.

Updating

For users

Updates are automatic — just restart Cowork and uvx will pull the latest version from PyPI.

For maintainers

1. Make changes to src/es_mcp/server.py
2. Bump the version in pyproject.toml
3. Build and publish:

   python -m build
   twine upload dist/*
   

4. Users get the new version automatically on next Cowork restart — no action needed on their end