kubesearch-mcp

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

Tool	kubesearch.dev equivalent	What it does
search_releases	/#cert-manager	Find charts by name; see who deploys them, ranked by popularity.
get_release	/hr/<id>	One chart's deployments. view: "summary" (default) digests the common spec.values; view: "deployments" paginates the repo list; view: "values" drills into a repo's full config.
search_images	/image#image cert-manager	Container image repositories and the tags used in the wild.
grep_values	/grep#grep cert-manager.io	Full-text grep across real-world Helm values for config examples.
status	—	Report the cached data's release date and row counts.

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)

Tool	What it does
repo_clone	Temporarily clone a repo (indexed owner/repo or an https Git URL) and return a handle + a curated file tree.
repo_list_files	List files in a clone (optional sub-path + glob).
repo_read_file	Read a text file from a clone (binary refused, large files truncated).
repo_grep	Substring-search a clone's text files; returns path:line matches. Takes limit and case_sensitive.
repo_grep_all	Substring-search the always-warm pool of top repos in one call, no clone step (see below).
repo_cleanup	Delete a clone early (clones also auto-expire; pool members are refused).

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

Variable	Default	What it does
MCP_AUTH_TOKEN	(unset — auth off)	Require Authorization: Bearer <token>. Accepts a comma-separated list, e.g. one token per client.
MCP_ALLOWED_ORIGINS	(unset — any origin)	Comma-separated Origin allowlist. When set, CORS reflects only these origins and other browser callers get 403. Requests with no Origin (normal MCP clients) are unaffected.
MCP_ALLOWED_HOSTS	(unset — any host)	Comma-separated Host allowlist. Guards against DNS rebinding, which matters for an instance reachable from a browser.
MCP_MAX_SESSIONS	100	Refuse new sessions past this many concurrent ones.
MCP_MAX_BODY_BYTES	4194304	Reject larger request bodies with 413.

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:

Variable	Default	Description
MCP_TRANSPORT	stdio (http in Docker)	stdio or http (streamable-http and streamablehttp are accepted aliases).
MCP_HTTP_HOST	0.0.0.0	HTTP bind host (http transport).
MCP_HTTP_PORT / PORT	3000	HTTP listen port. MCP_HTTP_PORT wins if both are set; the image sets neither, so a PaaS-injected PORT is honoured.
MCP_AUTH_TOKEN	(unset — auth off)	If set, every HTTP request must send Authorization: Bearer <token>. Accepts a single token or a comma-separated list of accepted tokens (e.g. one per client).
MCP_ALLOWED_ORIGINS	(unset — any)	Origin allowlist for /mcp; see Securing the HTTP transport.
MCP_ALLOWED_HOSTS	(unset — any)	Host allowlist for /mcp (DNS-rebinding guard).
MCP_MAX_BODY_BYTES	4194304	Max HTTP request body size; larger bodies get 413.
MCP_MAX_SESSIONS	100	Max concurrent HTTP sessions; further initialize calls get 503.
MCP_SESSION_TTL_MINUTES	30	Close an HTTP session after this long with no requests.
LOG_LEVEL	info	Minimum log severity to emit: debug, info, warn, or error. All logs are unstructured text on stderr.
KUBESEARCH_CACHE_DIR	~/.cache/kubesearch-mcp (/data in Docker)	Where the SQLite databases are cached.
KUBESEARCH_REFRESH_HOURS	24	How often to check for a newer daily release. 0 disables refresh (use cache forever). A failed check retries on a short backoff rather than waiting the full interval.
KUBESEARCH_DOWNLOAD_TIMEOUT_SECONDS	300	Wall-clock limit for downloading one database. Downloads also abort after 30s with no data received.
KUBESEARCH_MAX_DB_MB	512	Reject a database download larger than this.
GITHUB_TOKEN	(unset)	Lifts the GitHub API rate limit (60→5000/hr) used to resolve the latest release. Recommended.
KUBESEARCH_UPSTREAM_REPO	whazor/k8s-at-home-search	Source repo for the databases (override only for forks/testing).
KUBESEARCH_ENABLE_CLONE	true	Enable the repo_* clone/review tools. Set false to hide them entirely.
KUBESEARCH_CLONE_ALLOWED_HOSTS	(any)	Comma-separated host allowlist, e.g. github.com,gitlab.com. Empty = any public host.
KUBESEARCH_CLONE_ALLOW_PRIVATE	false	Permit cloning from private/loopback/link-local/metadata addresses (SSRF guard off).
KUBESEARCH_CLONE_DIR	<cacheDir>/clones	Where ephemeral clones live.
KUBESEARCH_CLONE_TTL_MINUTES	30	Auto-delete a clone after this much inactivity (timer resets on each access).
KUBESEARCH_CLONE_REFRESH_ON_CLONE	true	On a repeat clone of the same repo, git fetch + reset to the latest commit.
KUBESEARCH_CLONE_MAX_REPOS	5	Max concurrent cached clones (LRU-evicted).
KUBESEARCH_CLONE_MAX_CONCURRENT	2	Max git subprocesses running at once.
KUBESEARCH_CLONE_MAX_MB	200	Reject/clean a clone whose tree exceeds this size.
KUBESEARCH_CLONE_TIMEOUT_SECONDS	120	Hard timeout for the git clone subprocess.
KUBESEARCH_POOL_SIZE	15	How many top repos to keep permanently cloned for repo_grep_all. 0 disables the pool and hides the tool.
KUBESEARCH_POOL_MIN_RELEASES	20	Only repos with at least this many indexed HelmReleases are eligible for the star ranking.
KUBESEARCH_POOL_REPOS	(unset)	Comma-separated indexed repo names that replace the star ranking entirely (e.g. onedr0p/home-ops,bjw-s-labs/home-ops).

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.

Renovate keeps dependencies current: .github/workflows/renovate.yml runs it every 12 hours (and on dependency-dashboard or PR checkbox edits) with the policy in .renovaterc.json5, which extends the shared home-operations/renovate-config preset. It authenticates as a GitHub App so that CI runs on the PRs it opens.

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