indexsearch

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

npx @reneturcios/indexsearch list-indices

Or run the container image:

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

Variable	Meaning	Default
ES_URL	Cluster base URL	http://localhost:9200
INDEXSEARCH_URL	Fallback cluster base URL when ES_URL is unset	—
ES_API_KEY	API key, sent as Authorization: ApiKey <key>	unset (no auth)

CLI

# List indices
indexsearch list-indices

# Read one index's field mappings
indexsearch mappings products

# Search with query DSL (a bare clause, or a full {"query": ...} body)
indexsearch search products '{"match":{"name":"shoes"}}'

# Run an ES|QL query
indexsearch esql 'FROM products | SORT price DESC | LIMIT 5'

# Shard information for every index, or for one
indexsearch shards
indexsearch shards products

# Start the MCP server
indexsearch 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:

npx -y @reneturcios/indexsearch mcp

MCP client configuration:

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

Tools

Tool	Required	Optional	HTTP request	What it does
list_indices	—	—	GET /_cat/indices?format=json	List all available indices
get_mappings	index	—	GET /{index}/_mapping	Get field mappings for an index
search	index, query (object)	—	POST /{index}/_search with { "query": ... }	Search using query DSL
esql	query (string)	—	POST /_query with { "query": ... }	Run an ES
get_shards	—	index	GET /_cat/shards[/{index}]?format=json	Get 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

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live cluster
npm 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.