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.

Always-warm pool (repo_grep_all). kubesearch_grep_values only sees Helm spec.values
— that is all the upstream dataset contains. To grep across every resource kind
(Kustomizations, HTTPRoutes, ExternalSecrets, Talos configs, …) the server keeps the
KUBESEARCH_POOL_SIZE (default 15) most-starred indexed repos permanently cloned and
repo_grep_all searches them in one call. Ranking by raw stars alone would fill the pool with
CLI tools and Argo-only repos that have nothing greppable, so only repos with at least
KUBESEARCH_POOL_MIN_RELEASES (default 20) indexed HelmReleases are considered; set
KUBESEARCH_POOL_REPOS=onedr0p/home-ops,bjw-s-labs/home-ops,… to pick the membership
yourself. Pool clones live under <cloneDir>/pool/<owner>__<repo>, use the indexed repo name
as their handle (so repo_read_file can follow a hit directly, and repo_clone of a pool
member reuses it), never expire, don't count toward KUBESEARCH_CLONE_MAX_REPOS, and survive
shutdown so the next start adopts them with a shallow git fetch instead of re-cloning
(~4 MB per repo on disk). Membership is recomputed whenever a new dataset release lands and
the copies are refreshed on the KUBESEARCH_REFRESH_HOURS cadence. Warm-up runs in the
background and never blocks startup; while it's in progress repo_grep_all reports
pool.syncing: true and searches whatever is ready. KUBESEARCH_POOL_SIZE=0 disables the
pool and hides the tool.

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).

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