artisan-es-reader-plugin 0.2.0

Elasticsearch MCP server — query logs with or without SSH tunnel

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. Configure the MCP server

Open claude_desktop_config.json:

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

Add the entry inside "mcpServers": { }:

{
  "mcpServers": {
    "elasticsearch-logs": {
      "command": "uvx",
      "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"],
      "env": {
        "ES_HOST": "localhost",
        "ES_PORT": "9200",
        "ES_USERNAME": "your-es-username",
        "ES_PASSWORD": "your-es-password",
        "ES_USE_SSL": "true",
        "ES_VERIFY_CERTS": "false",
        "SSH_HOST": "your-bastion-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "ubuntu",
        "SSH_PEM_FILE": "C:\\Users\\your-name\\path\\to\\key.pem",
        "SSH_REMOTE_ES_HOST": "localhost",
        "SSH_REMOTE_ES_PORT": "9200",
        "SSH_LOCAL_PORT": "0"
      }
    }
  }
}

Each team member only needs to fill in these personal values:

Variable	Description
ES_USERNAME	Elasticsearch username
ES_PASSWORD	Elasticsearch password
SSH_HOST	Bastion / jump host IP or hostname
SSH_PEM_FILE	Absolute path to your local PEM key file

Windows paths must use double backslashes in JSON: C:\\Users\\your-name\\key.pem

4. Restart Cowork

The SSH tunnel starts automatically on first tool use.

---

Notes

• ES_HOST is only used for direct connections. When SSH_HOST is set, traffic routes through the tunnel and ES_HOST is ignored.
• ES_USE_SSL: set true if your Elasticsearch runs HTTPS.
• ES_VERIFY_CERTS: set false for self-signed certificates.
• SSH_LOCAL_PORT: 0 = auto-pick a free local port.
• To connect without SSH tunnel, leave SSH_HOST empty.

---

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

---

Available tools

Tool	What it does
list_indices	List indices (supports glob pattern)
search_logs	Full-text search with filters, sort, pagination
get_recent_errors	Error-level entries from the last N minutes
get_index_mapping	Field schema for an index
run_aggregation	Run a custom ES aggregation
connection_info	Show active connection / tunnel status