elastic-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for AI assistants (and humans) working in this repository.

This project was vibe coded. It is typechecked and unit-tested; keep both green on every change.

What this is

A Model Context Protocol (MCP) server for Elasticsearch, over the stdio transport. Read-only by default, with optional write tools. Written in JavaScript with JSDoc types checked by TypeScript (@ts-check / checkJs) — there is no build step; the .js files in src/ are what runs.

Commands

npm run typecheck   # tsc --noEmit (must pass)
npm test            # node --test (must pass)
npm start           # node src/index.js (needs ELASTICSEARCH_URL)

Project layout

src/
  index.js        entry point; resolves version, builds client + server, wires stdio
  server.js       builds the MCP server and registers tool groups
  es-client.js    config parsing, version probe/selection, client construction
  connection.js   base-path-aware UndiciConnection subclass (factory)
  util.js         tool-result + error helpers (jsonResult, errorResult, toToolResult, isAuthorizationError)
  tools/
    search.js     search, count, esql, get_document
    indices.js    list_indices, get_mapping, get_settings, get_aliases, list_shards
    cluster.js    cluster_health, cluster_stats, cluster_info, list_nodes
    kibana.js     get_kibana_object
    write.js      index_document, update_document, delete_document, create_index, delete_index
test/
  config.test.js  readConfig / splitOriginAndPrefix
  util.test.js    tool-result helpers
  server.test.js  end-to-end tool routing against a fake Elasticsearch HTTP server

Architecture notes

• Base path support (connection.js): the official client routes requests against the node origin only and drops any URL path. createPrefixedConnection(UndiciConnectionBase, prefix) returns a subclass that re-prepends the prefix to every request. The base class is passed in so each client major subclasses its own bundled UndiciConnection.
• Dual 8.x / 9.x support (es-client.js): the v9 client sends compatible-with=9, which 8.x clusters reject. Both client majors are installed (@elastic/elasticsearch for v9, the elasticsearch8 alias for v8). resolveMajor() honors ELASTICSEARCH_API_VERSION, else probes the root endpoint with a plain application/json request. The probe needs cluster:monitor/main; on any failure it falls back to the v8 client, which both 8.x and 9.x accept. Cross-major type incompatibilities are bridged with casts confined to the v8 branch of createClient.
• Privilege fallbacks (tools/indices.js): list_indices falls back from _cat/indices (needs cluster monitor) to _resolve/index, and get_mapping from getMapping (needs view_index_metadata) to _field_caps (needs only read). Each remembers the authorization failure in a closure flag for the process lifetime so it stops retrying the rejected endpoint.
• Kibana saved objects (tools/kibana.js): get_kibana_object reads .kibana_analytics + .kibana directly (user content vs. system content), decodes the JSON-as-string fields Kibana stores inline (visState, searchSourceJSON, ...) via decodeInlineJson, and resolves each references[] entry to its title. Those are restricted system indices, so the API key needs an allow_restricted_indices read entry on .kibana*.
• Results & errors (util.js): every tool returns through toToolResult, which serializes success with jsonResult and converts throws with errorResult. errorResult surfaces Elasticsearch ResponseError status + reason and never emits "[object Object]". Use isAuthorizationError to detect 403 / security_exception.
• Write tools are off by default; registered only when ELASTICSEARCH_ENABLE_WRITES=true (server.js). Mutating tools carry destructiveHint annotations.