Indexsearch

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.1.0Updated Nov 7, 2026

Elasticsearch tools: indices, mappings, query DSL search, ES|QL, and shards.

VerifiedSTDIODesktop onlyDatabasesData & Analytics

Overview

AI-generated overview

Elasticsearch MCP server that lets an assistant list indices, read mappings, run query DSL searches and ES|QL queries, and inspect shards.

What you can do
  • List indices and inspect shard placement across the cluster
  • Read field mappings for a specific index
  • Run searches against an index using Elasticsearch query DSL
  • Run ES|QL queries through the cluster's query endpoint
  • Return the cluster's parsed JSON replies, with non-JSON replies kept under a raw key
When to use it
Useful when an assistant needs to explore or query an existing Elasticsearch cluster: checking which indices exist, understanding a schema before writing queries, running ad-hoc searches or ES|QL, or diagnosing shard layout.
Requirements
Runs locally over stdio via npx or the Docker image; the mcp subcommand starts the server. Needs a reachable Elasticsearch cluster, set with ES_URL (default or the fallback INDEXSEARCH_URL, and optionally ES_API_KEY for authentication. No account or other credentials are declared.
Before you install
ES_API_KEY is passed as an Authorization header, so the key inherits whatever access the cluster grants it; prefer a read-only key. Searches and ES|QL queries are sent to the cluster and may be expensive or return sensitive index data. Index names are validated locally, but the server does not restrict which indices or queries an assistant can run.

Installation

In SourceWeft

  1. Open Indexsearch in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

indexsearch

indexsearch gives an agent — or you, at a terminal — the five core Elasticsearch tools: see which indices exist, read an index's field mappings, run a search in query DSL, run an ES|QL query, and inspect shard placement. Everything goes through the cluster's own HTTP API; there is no bundled client library and no second query language to learn.

Each tool call is first mapped to a plain HTTP request — method, path, and JSON body — and that mapping is the whole contract: GET /_cat/indices?format=json, GET /{index}/_mapping, POST /{index}/_search, POST /_query, GET /_cat/shards. Transport is an injectable fetch function, which is what the test suite drives; no live cluster is needed to verify behaviour, and no result is ever invented when a cluster is unreachable or answers with an error.

Install

bash
npx @reneturcios/indexsearch list-indices

Or run the container image:

bash
docker run -i ghcr.io/cloudcorprecords/indexsearch

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead, and pass the cluster settings as environment variables (-e ES_URL=...).

Configuration

VariableMeaningDefault
ES_URLCluster base URLhttp://localhost:9200
INDEXSEARCH_URLFallback cluster base URL when ES_URL is unset—
ES_API_KEYAPI key, sent as Authorization: ApiKey <key>unset (no auth)

CLI

bash
# List indicesindexsearch list-indices
# Read one index's field mappingsindexsearch mappings products
# Search with query DSL (a bare clause, or a full {"query": ...} body)indexsearch search products '{"match":{"name":"shoes"}}'
# Run an ES|QL queryindexsearch esql 'FROM products | SORT price DESC | LIMIT 5'
# Shard information for every index, or for oneindexsearch shardsindexsearch shards products
# Start the MCP serverindexsearch mcp
indexsearch --version

Exit codes: 0 on success, 1 when the request or the cluster fails (the error names the HTTP status or the unreachable URL), 2 for usage errors.

Index names are validated before any request is made: names carrying characters Elasticsearch forbids in index names (whitespace, /, *, ?, ", <, >, |, ,, #, :, \) are rejected locally.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

bash
npx -y @reneturcios/indexsearch mcp

MCP client configuration:

json
{  "mcpServers": {    "indexsearch": {      "command": "npx",      "args": ["-y", "@reneturcios/indexsearch", "mcp"],      "env": { "ES_URL": "http://localhost:9200" }    }  }}

Tools

ToolRequiredOptionalHTTP requestWhat it does
list_indices——GET /_cat/indices?format=jsonList all available indices
get_mappingsindex—GET /{index}/_mappingGet field mappings for an index
searchindex, query (object)—POST /{index}/_search with { "query": ... }Search using query DSL
esqlquery (string)—POST /_query with { "query": ... }Run an ES
get_shards—indexGET /_cat/shards[/{index}]?format=jsonGet shard information for all or specific indices

Replies are returned as the cluster's parsed JSON. A non-JSON reply is returned under a raw key rather than being dropped, and an empty reply reads as an empty object.

Development

bash
npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, no network, no live clusternpm run dev     # run the CLI from source via tsx

Request construction, validation, header and body assembly, error surfacing, and settings resolution are all covered by tests that drive the core through a fake fetch and assert the exact paths and bodies.

License

MIT — see LICENSE.

Source: README.md at commit 0798c6b

Tools

5

list_indices

List all available Elasticsearch indices

Takes no parameters.

get_mappings

Get field mappings for a specific Elasticsearch index

Parametersindexrequired

esql

Perform an Elasticsearch ES|QL query

Parametersqueryrequired

get_shards

Get shard information for all or specific indices

Parametersindex

Version history

1
  1. v0.1.0LatestOct 31, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts