kubesearch-mcp
An MCP server for searching kubesearch.dev’s public home-ops Kubernetes index and reviewing real repo manifests.
Search Flux HelmReleases/Argo Applications by chart name, ranked by popularity and paginated.
Inspect one chart’s deployments, community value settings, examples, and full per-repo
spec.values.Search container image repositories and tags seen across clusters.
Full-text grep real-world Helm values for configuration examples.
Check cached dataset freshness and row counts.
Temporarily clone public Git repos in a sandbox to list, read, grep, and clean up files.
Grep an always-warm pool of top indexed repos across all resource kinds without cloning.
Use workflow prompts for tasks like comparing deployments, adopting charts, finding examples, picking images, and reviewing repos.
Provides search and review capabilities for Argo Applications, including application search, deployment inspection, and image and values grep across hundreds of public home-ops Kubernetes Git repositories.
Provides search and review capabilities for Flux HelmReleases, including chart search, deployment inspection, and image and values grep across hundreds of public home-ops Kubernetes Git repositories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kubesearch-mcp search for cert-manager HelmReleases"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
| Find charts by name; see who deploys them, ranked by popularity. |
|
| One chart's deployments. |
|
| Container image repositories and the tags used in the wild. |
|
| Full-text grep across real-world Helm values for config examples. |
| — | 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 |
| Temporarily clone a repo (indexed |
| List files in a clone (optional sub-path + glob). |
| Read a text file from a clone (binary refused, large files truncated). |
| Substring-search a clone's text files; returns |
| Substring-search the always-warm pool of top repos in one call, no clone step (see below). |
| 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) — thespec.valuesJSON (powers grep and image search).
Data is refreshed automatically when a newer daily release appears (see
KUBESEARCH_REFRESH_HOURS).
Related MCP server: mcp-helm
Quick start (local, stdio)
npm install
npm run buildAdd it to Claude Code:
claude mcp add kubesearch -- node /absolute/path/to/kubesearch-mcp/dist/index.jsOr 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:latestPublished 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 -dThe container runs as the unprivileged
nodeuser (uid 1000) and writes cached databases and clones under/data. The named volume indocker-compose.ymlis 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), orrepo_cloneand 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'sHEALTHCHECKuses, 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 |
| (unset — auth off) | Require |
| (unset — any origin) | Comma-separated |
| (unset — any host) | Comma-separated |
|
| Refuse new sessions past this many concurrent ones. |
|
| 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-mcpConfiguration
All configuration is via environment variables:
Variable | Default | Description |
|
|
|
|
| HTTP bind host (http transport). |
|
| HTTP listen port. |
| (unset — auth off) | If set, every HTTP request must send |
| (unset — any) |
|
| (unset — any) |
|
|
| Max HTTP request body size; larger bodies get 413. |
|
| Max concurrent HTTP sessions; further |
|
| Close an HTTP session after this long with no requests. |
|
| Minimum log severity to emit: |
|
| Where the SQLite databases are cached. |
|
| How often to check for a newer daily release. |
|
| Wall-clock limit for downloading one database. Downloads also abort after 30s with no data received. |
|
| Reject a database download larger than this. |
| (unset) | Lifts the GitHub API rate limit (60→5000/hr) used to resolve the latest release. Recommended. |
|
| Source repo for the databases (override only for forks/testing). |
|
| Enable the |
| (any) | Comma-separated host allowlist, e.g. |
|
| Permit cloning from private/loopback/link-local/metadata addresses (SSRF guard off). |
|
| Where ephemeral clones live. |
|
| Auto-delete a clone after this much inactivity (timer resets on each access). |
|
| On a repeat clone of the same repo, |
|
| Max concurrent cached clones (LRU-evicted). |
|
| Max |
|
| Reject/clean a clone whose tree exceeds this size. |
|
| Hard timeout for the |
|
| How many top repos to keep permanently cloned for |
|
| Only repos with at least this many indexed HelmReleases are eligible for the star ranking. |
| (unset) | Comma-separated indexed repo names that replace the star ranking entirely (e.g. |
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 hooksThen:
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 locallyThe 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
Available Tools
11 toolsget_releaseGet HelmRelease detailsARead-onlyIdempotent
Get details for one chart by its kubesearch.dev release id (the id from search_releases, e.g. 'ghcr.io-home-operations-charts-mirror-cert-manager'). Three views, controlled by view:
summary(default): a compact digest of how the community configures the chart — the most commonly-setspec.valuespaths with their typical values, plus a couple of full example configs. Start here.deployments: the paginated list of every repo deploying the chart (no values) — use it to find a repo to drill into.values: the full parsedspec.valuesfor selected deployments — narrow withrepoand/orvalue_pathsto fetch just the config (or subtree) you care about. This is the drill-down; prefersummaryfirst. Note:chart_source_urlis the normalized kubesearch.dev grouping key, not necessarily the pullable chart. ForchartRef/OCIRepository releases the real chart is insource_urls(group) and each deployment'ssource_url+source_tag;resolved_chartsurfaces the true chart name when it differs fromchart. Confirm by cloning the deployment's repo (repo_clone) and reading its OCIRepository source.yaml.
Inputs: id (required), top, repo, view, +4 more. Returns: id, view, chart, shown, +14 more
grep_valuesGrep HelmRelease valuesARead-onlyIdempotent
Full-text grep across the Helm spec.values of every indexed HelmRelease/Application (substring match). Great for finding real-world examples of a config key or value, e.g. 'cert-manager.io', 'nodeSelector', 'gatus'. Returns the matched key path, a snippet, and the source file. Mirrors the kubesearch.dev /grep search.
Inputs: query (required), limit, offset, case_sensitive. Returns: query, shown, offset, results, +3 more
repo_cleanupDelete a cloned repositoryAIdempotent
Delete a temporary clone created by repo_clone (frees disk before its TTL). Clones are also auto-deleted after inactivity, so this is optional but polite.
Inputs: handle (required). Returns: handle, removed
repo_cloneClone a repository (temporary)A
Temporarily clone a public Git repository so you can review its actual files. Accepts an indexed home-ops repo name (e.g. 'onedr0p/home-ops' — resolved to its real clone URL and branch) or a full https Git URL. The clone is shallow, sandboxed, size/time-limited, and auto-deleted after a TTL. Returns a handle to use with repo_list_files, repo_read_file, and repo_grep, plus a curated file tree to get you started. Call repo_cleanup when done.
Inputs: repo (required). Returns: tree, branch, handle, pinned, +6 more
repo_grepGrep a cloned repositoryARead-onlyIdempotent
Search the text contents of a previously cloned repository (by handle) for a substring. Optionally restrict to files matching a glob. Returns file paths, line numbers, and matching lines. If truncated is set, narrow the search with a longer query or a glob rather than paging.
Inputs: query (required), handle (required), glob, limit, +1 more. Returns: query, handle, matches, truncated, +1 more
repo_grep_allGrep the always-warm pool of top reposARead-onlyIdempotent
Substring-search the actual files of the most popular indexed home-ops repositories at once — no clone step needed. The server keeps these repos permanently cloned, so this covers every resource kind (Kustomizations, Ingress/HTTPRoute, ExternalSecrets, Talos configs, …), not just Helm values like grep_values. Hits are grouped by repo, most-starred first, and each group carries a handle you can pass straight to repo_read_file / repo_list_files / repo_grep for the follow-up. pool reports which repos were searchable: while pool.syncing is true and ready is below size the pool is still warming up, so an empty result is not final — retry after a short pause.
Inputs: query (required), glob, limit, max_per_repo, +1 more. Returns: pool, query, repos, truncated, +2 more
repo_list_filesList files in a cloned repositoryARead-onlyIdempotent
List files in a previously cloned repository (by handle). Optionally scope to a sub-path and/or filter with a glob (e.g. '/*.yaml', 'kubernetes/'). Use the handle returned by repo_clone.
Inputs: handle (required), glob, path. Returns: path, handle, entries, truncated
repo_read_fileRead a file from a cloned repositoryARead-onlyIdempotent
Read a text file from a previously cloned repository (by handle and relative path). Binary files are refused and large files are truncated. Use the handle returned by repo_clone.
Inputs: path (required), handle (required), max_bytes. Returns: path, bytes, handle, content, +1 more
search_imagesSearch container imagesARead-onlyIdempotent
Search kubesearch.dev for container image repositories used across public home-ops clusters (substring match on the image repository, case-insensitive). Returns each matching image repository, the tags seen in the wild, how many deployments use it, and a few sample repos. Equivalent to the kubesearch.dev /image search.
Inputs: query (required), limit, offset. Returns: query, shown, offset, results, +3 more
search_releasesSearch HelmReleasesARead-onlyIdempotent
Search kubesearch.dev for Flux HelmReleases / Argo Applications by chart name (substring, case-insensitive). Mirrors the kubesearch.dev homepage search (e.g. 'cert-manager'). Results are grouped by chart source and ranked by how many public home-ops repos deploy them. Each result includes an id you can pass to get_release for full details, plus a kubesearch.dev link.
Note: chart_source_url is a NORMALIZED grouping key (it matches kubesearch.dev's /hr/<id> grouping and intentionally collapses related registries, e.g. all bjw-s variants into 'oci://ghcr.io/bjw-s-labs/charts/'). For chartRef/OCIRepository releases the actual pullable chart is in source_urls (group) and each repo's source_url (+ source_tag); resolved_chart flags when the real chart name differs from chart.
Inputs: query (required), limit, offset. Returns: query, shown, offset, results, +3 more
statusKubesearch data statusARead-onlyIdempotent
Report the freshness and size of the locally cached kubesearch.dev data: the release tag (date), when it was loaded, the cache directory, and row counts. Useful to confirm how current the search data is.
Inputs: no named parameters. Returns: tag, cacheDir, loadedAt, helmReleases, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have crisp, distinct purposes: clone/list/read/grep/cleanup on a handle vs. index-wide searches (search_releases, search_images, get_release, grep_values). The only soft overlaps are grep_values vs repo_grep_all (both full-text across many repos, differing only in scope: Helm values vs all files) and repo_grep vs repo_grep_all (handle vs pool); the descriptions do call these out, so an attentive agent can separate them.
Everything is snake_case and grouped by prefix family (repo_* for clone operations, search_* for index lookups), which is readable and predictable. Minor deviations: repo_clone is prefix+verb while search_releases/get_release are verb_noun, and 'status' is a bare noun with no verb.
11 tools is well within a healthy range for a search-plus-repo-inspection server. Each tool earns its place: discovery (1), drill-down (1), index greps (2), clone lifecycle (4), and a diagnostics call.
The surface covers the full workflow — discover charts/images, inspect values, clone a repo, list/read/grep files, and clean up — with no dead ends. The main gap is that there is no way to browse or search the list of indexed home-ops repos directly; repo discovery is only implicit through search_releases or repo_grep_all's pool.
Maintenance
Related MCP Connectors
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Give your AI assistant access to real Helm chart data. No more hallucinated values.yaml files.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs like Claude to securely execute Kubernetes CLI tools (kubectl, helm, istioctl, argocd) across multiple clusters through dynamic kubeconfig support, allowing natural language Kubernetes management and operations.5MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI assistants with real Helm chart data from repositories, enabling accurate queries of chart values, versions, dependencies, and search without hallucination.MIT
- FlicenseNot gradedqualityDmaintenanceExposes Kubernetes cluster management tools to LLMs, enabling querying pods, deployments, logs, metrics, and managing port forwards via natural language.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with Argo CD applications, managing clusters, applications, and resources through natural language.Apache 2.0