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.