Connect Elasticsearch to Claude Code

Inspect indices, mappings and cluster health, then search, count and aggregate documents. Add Toolspoke to Claude Code once and it can use 12 Elasticsearch actions. Your Elasticsearch credential stays in Toolspoke, and you choose which actions Claude Code may call.

Set it up in Claude Code

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. Install Elasticsearch and connect it

    Add Elasticsearch to a project in your Toolspoke workspace.

    API key. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Cluster URL
    The Elasticsearch endpoint root, with its port. Elastic Cloud shows it under the deployment's connection details; a self-managed cluster is usually port 9200. This is the Elasticsearch address, not the Kibana one.
    API key
    Paste the `encoded` value the create-API-key call returns, or the key shown in Kibana under Stack Management → API keys. Give it `read` and `view_index_metadata` on the indices it should reach, plus cluster `monitor`, that is what makes the install read-only at the server rather than only here.
  3. Choose what Claude Code may do

    All 12 actions only read, and any of them can be switched off for a project.

What you can ask Claude Code for

A few of the Elasticsearch actions that only read, so they are safe to try first.

  • Report the cluster name and the Elasticsearch version
  • List indices with their health, document count and size on disk
  • List index aliases and what they point at, including which index an alias writes to
  • List the nodes in the cluster with their roles, heap and memory use, CPU and load average

What Claude Code can do in Elasticsearch

12 actions read.

Reads

  • Server info

    Report the cluster name and the Elasticsearch version. Call this first to confirm the URL and the API key work, it takes no arguments and reads nothing about the data.

  • Cluster health

    Report the cluster's health: the green/yellow/red status, node counts, and how many shards are active, relocating, initialising or unassigned. Ask for the indices level to get the same breakdown per index.

  • List indices

    List indices with their health, document count and size on disk. The index argument is a pattern, so * lists everything and logs-* lists one family. Sizes are in bytes so they sort correctly.

  • List aliases

    List index aliases and what they point at, including which index an alias writes to. Use it when a query names something that turns out not to be an index.

  • List nodes

    List the nodes in the cluster with their roles, heap and memory use, CPU and load average. Use it to tell a cluster problem from a slow query.

  • Get mapping

    Return the field mappings of one index or index pattern: every field with its type and any sub-fields. Call this before writing a query, whether a field is text, keyword or date decides which query works on it.

  • Get settings

    Return one index's settings: shard and replica counts, refresh interval, analysers and lifecycle policy. Use it when an index behaves differently from its neighbours.

  • Search

    Run a query DSL search and return the matching documents. Call get_mapping first so the field types are right. Keep `size` small, the documents come back in full. Sorting on a field replaces the relevance score, so ask for a sort only when you want one.

  • Count documents

    Count the documents matching a query without returning any of them. Use it to size a result before searching, and to check a filter is selective enough.

  • Aggregate

    Run aggregations and return only the buckets, never the documents. This is how you get counts by term, histograms over time and statistics on a field. `size` is fixed at 0, so no document bodies come back.

  • Get document

    Fetch one document by its id. Use it after a search has given you an id, when you want the whole document rather than the fields the search returned.

  • Validate query

    Check whether a query is valid against an index and, when it is not, say why, without running it. Use it to debug a query that returns an error, and to check an expensive query parses before paying for it.

Elasticsearch in Claude Code: questions

Does Claude Code see my Elasticsearch credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Will 12 actions crowd Claude Code's context?

No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the Elasticsearch action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Can I add it once for every project?

Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.

What does it cost?

Tool calls are free on every plan, and a Elasticsearch call does not run in a sandbox, so it bills nothing.

Try Elasticsearch in Claude Code

Free to start, and tool calls cost nothing on any plan.