kubesearch-mcp

An MCP server that lets an LLM search kubesearch.dev — a search engine over Flux HelmReleases and Argo Applications across hundreds of public "home-ops" Kubernetes Git repositories.

It reproduces all of kubesearch.dev's search modes as tools, and can temporarily clone a repo so the model can review its actual manifests.

Search tools

All search tools are annotated read-only and return a typed structuredContent payload alongside the equivalent text. They page with limit/offset and report has_more, and their result ordering is global (matches are ranked across the whole result set before the page is cut), so paging never repeats or skips an entry.

In the values view, value_paths accepts the paths printed in the summary view's common_settings verbatim, array forms like route.hostnames[] included. A single deployment whose config is too large for one response is always returned when it is first on the page, so { repo, limit: 1 } reaches any deployment; larger ones later in a page are reported individually via values_omitted and omitted_count.

Repository review tools (enabled by default; set KUBESEARCH_ENABLE_CLONE=false to disable)

Clones are sandboxed: shallow (--depth 1, blob-size filtered), run with git via execFile (no shell) and a scrubbed environment, size/TTL/concurrency-capped, confined to a per-clone temp dir, with path-traversal and symlink-escape protection. By default any public host is allowed but private/loopback/link-local/metadata addresses are blocked (see env vars below).

Lifecycle: a clone is kept while it's being used and auto-deleted after KUBESEARCH_CLONE_TTL_MINUTES of inactivity (the timer resets on every access). Repeat repo_clone calls for the same repo+branch are deduplicated to a single working copy and (by default) refreshed with a shallow git fetch + hard reset to the latest commit, so a long-lived clone never goes stale — set KUBESEARCH_CLONE_REFRESH_ON_CLONE=false to reuse without pulling. Reads (repo_read_file/repo_grep/repo_list_files) are served from the snapshot and do not pull, so an in-progress review stays stable; re-run repo_clone to pull.

Concurrent repo_clone calls for the same repo share a single git invocation, at most KUBESEARCH_CLONE_MAX_CONCURRENT git subprocesses run at once, and clone directories stranded by an ungraceful restart are reaped at startup.

Prompts (workflow shortcuts)

Server-provided MCP prompts that chain the tools: kubesearch_compare_deployments, kubesearch_adopt_chart, kubesearch_find_config_examples, kubesearch_pick_image, and (when cloning is enabled) kubesearch_review_repo.

How it works

kubesearch.dev has no live API; it publishes its index as SQLite databases on the whazor/k8s-at-home-search GitHub releases (a new date-tagged release daily). This server downloads and caches those databases locally and queries them with SQL — fast, offline-capable, and identical to what the website shows. Two complementary databases are used and joined on the YAML file URL:

• repos.db (~7 MB) — chart/release/repo metadata.

• repos-extended.db (~37 MB) — the spec.values JSON (powers grep and image search).

Data is refreshed automatically when a newer daily release appears (see KUBESEARCH_REFRESH_HOURS).

Related MCP server: K8s MCP Server

Quick start (local, stdio)

npm install
npm run build

Add it to Claude Code:

claude mcp add kubesearch -- node /absolute/path/to/kubesearch-mcp/dist/index.js

Or in a Claude Desktop / MCP client config:

{
  "mcpServers": {
    "kubesearch": {
      "command": "node",
      "args": ["/absolute/path/to/kubesearch-mcp/dist/index.js"]
    }
  }
}

The first call downloads the databases into the cache dir (a few seconds); subsequent runs reuse the cache.

Docker deployment (HTTP)

The image defaults to the Streamable HTTP transport, which is what you want for a long-running server that MCP clients connect to over the network.

docker run -d --name kubesearch-mcp \
  -p 3000:3000 \
  -v kubesearch-data:/data \
  -e GITHUB_TOKEN=ghp_xxx \
  ghcr.io/perfectra1n/kubesearch-mcp:latest

Published tags: latest (default branch), vX.Y.Z and X.Y (releases), and sha-<short> for a specific commit. To build it yourself instead, use docker build -t kubesearch-mcp . and substitute that image name.

Mount /data as shown: it holds the cached databases, so without it every restart re-downloads ~44 MB.

Or with Compose:

docker compose up -d

The container runs as the unprivileged node user (uid 1000) and writes cached databases and clones under /data. The named volume in docker-compose.yml is writable out of the box. If you bind-mount a host directory instead, make it writable by uid 1000 (e.g. chown -R 1000:1000 ./data), or repo_clone and refreshes will fail with "Permission denied".

The MCP endpoint is http://<host>:3000/mcp. Two health endpoints are exposed:

• GET /healthz — liveness. Always 200 while the process is up. This is what the image's HEALTHCHECK uses, so a slow initial download can't get the container restarted mid-download.

• GET /readyz — readiness. 503 until a release is loaded, then 200. Use this for Kubernetes readiness probes and load-balancer checks, so traffic isn't sent to a pod whose first queries would fail.

Point an MCP client at it:

{
  "mcpServers": {
    "kubesearch": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

(The Authorization header is only required when MCP_AUTH_TOKEN is set.)

Securing the HTTP transport

The HTTP transport ships open. Out of the box there is no authentication, CORS is *, and the image binds 0.0.0.0. That is fine on a trusted network or behind a reverse proxy that authenticates for you; it is not fine on a public interface. Before exposing the port beyond a network you control:

The server logs a warning at startup if it binds a non-loopback address with authentication disabled. Terminate TLS at a proxy; the server speaks plain HTTP.

Running the container over stdio instead

If you prefer to have a client spawn the container per session:

docker run -i --rm -v kubesearch-data:/data -e MCP_TRANSPORT=stdio kubesearch-mcp

Configuration

All configuration is via environment variables:

Development

mise pins the toolchain and owns the dev/release lifecycle, so every command below is the same one CI runs. One-time setup:

mise install    # installs Node, lefthook, shellcheck; also installs the git hooks

Then:

mise tasks            # list every task with a description
mise run dev          # run from source via tsx
mise run test         # vitest (unit + offline integration against a fixture DB)
mise run lint         # typecheck + prettier --check + shellcheck
mise run fmt          # format in place with prettier
mise run build        # bundle to dist/ with tsup
mise run ci           # the full local gate: fmt-check, typecheck, test, build
mise run smoke        # end-to-end against live upstream data (needs network)
mise run image        # build the container image locally

The underlying npm run <script> commands still work if you'd rather not use mise; mise is a thin wrapper plus a pinned toolchain. Exact tool versions live in .mise/config.toml with per-platform checksums in .mise/mise.lock, which CI enforces via mise install --locked; package.json's engines.node records the minimum supported runtime.

A lefthook pre-commit hook formats staged files with prettier and re-stages them, and runs shellcheck on shell scripts. It deliberately doesn't run tests or the typechecker — that's CI's job, so committing stays fast. mise install wires the hook; lefthook install re-syncs it if needed.

Tests run fully offline against a small fixture database that mirrors the real schema. They cover the domain logic, the download/refresh paths (with a stubbed fetch), the HTTP transport end to end, and the tools themselves through an in-memory MCP client — which means the SDK validates every response against its declared outputSchema. The releaseKey/mergeHelmURL slug logic is ported verbatim from upstream and locked with test vectors so generated /hr/<id> links match the real site.

typecheck and test run on every push and pull request, and the container image is only published if they pass.

Credits

All data comes from kubesearch.dev / whazor/k8s-at-home-search. To include your own cluster, make the repo public and add the k8s-at-home or kubesearch GitHub topic.

License

MIT