Skip to main content
Glama
kubesearch-mcp

kubesearch-mcp

by perfectra1n

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PORTNoAlternative for MCP_HTTP_PORT.3000
GITHUB_TOKENNoLifts the GitHub API rate limit (60→5000/hr) used to resolve the latest release. Recommended.
MCP_HTTP_HOSTNoHTTP bind host (HTTP transport).0.0.0.0
MCP_HTTP_PORTNoHTTP listen port (HTTP transport). Also accepts PORT.3000
MCP_TRANSPORTNoTransport mode: stdio or http. Defaults to 'stdio' outside Docker, 'http' inside Docker.stdio
MCP_AUTH_TOKENNoIf set, every HTTP request must send Authorization: Bearer <token>.
KUBESEARCH_CACHE_DIRNoWhere the SQLite databases are cached. In Docker default is /data.~/.cache/kubesearch-mcp
KUBESEARCH_CLONE_DIRNoWhere ephemeral clones live.<cacheDir>/clones
KUBESEARCH_CLONE_MAX_MBNoReject/clean a clone whose tree exceeds this size.200
KUBESEARCH_ENABLE_CLONENoEnable the repo_* clone/review tools. Set 'false' to hide them entirely.true
KUBESEARCH_REFRESH_HOURSNoHow often to check for a newer daily release. 0 disables refresh.24
KUBESEARCH_UPSTREAM_REPONoSource repo for the databases (override only for forks/testing).whazor/k8s-at-home-search
KUBESEARCH_CLONE_MAX_REPOSNoMax concurrent cached clones (LRU-evicted).5
KUBESEARCH_CLONE_TTL_MINUTESNoAuto-delete a clone after this much inactivity.30
KUBESEARCH_CLONE_ALLOWED_HOSTSNoComma-separated host allowlist. Empty = any public host.
KUBESEARCH_CLONE_ALLOW_PRIVATENoPermit cloning from private/loopback/link-local/metadata addresses (SSRF guard off).false
KUBESEARCH_CLONE_TIMEOUT_SECONDSNoHard timeout for the git clone subprocess.120
KUBESEARCH_CLONE_REFRESH_ON_CLONENoOn a repeat clone of the same repo, git fetch + reset to latest commit.true

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
search_releasesA

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.

get_releaseA

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-set spec.values paths 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 parsed spec.values for selected deployments — narrow with repo and/or value_paths to fetch just the config (or subtree) you care about. This is the drill-down; prefer summary first. Note: chart_source_url is the normalized kubesearch.dev grouping key, not necessarily the pullable chart. For chartRef/OCIRepository releases the real chart is in source_urls (group) and each deployment's source_url + source_tag; resolved_chart surfaces the true chart name when it differs from chart. Confirm by cloning the deployment's repo (repo_clone) and reading its OCIRepository source.yaml.

search_imagesA

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.

grep_valuesA

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.

statusA

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.

repo_cloneA

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.

repo_list_filesA

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.

repo_read_fileA

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.

repo_grepA

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.

repo_grep_allA

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.

repo_cleanupA

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.

Prompts

Interactive templates invoked by user choice

NameDescription
kubesearch_compare_deploymentsCompare how the most popular home-ops repos configure a given Helm chart.
kubesearch_adopt_chartProduce a recommended, community-aligned way to deploy a chart.
kubesearch_find_config_examplesFind real-world examples of a config key or value across home-ops clusters.
kubesearch_pick_imageFind which container image repository and tag the community actually runs for an app.
kubesearch_review_repoTemporarily clone a repository and review its Kubernetes/Flux/Helm setup.

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4.2/5.0

Scored across 11 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo recent community issues