kubesearch-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | Alternative for MCP_HTTP_PORT. | 3000 |
| GITHUB_TOKEN | No | Lifts the GitHub API rate limit (60→5000/hr) used to resolve the latest release. Recommended. | |
| MCP_HTTP_HOST | No | HTTP bind host (HTTP transport). | 0.0.0.0 |
| MCP_HTTP_PORT | No | HTTP listen port (HTTP transport). Also accepts PORT. | 3000 |
| MCP_TRANSPORT | No | Transport mode: stdio or http. Defaults to 'stdio' outside Docker, 'http' inside Docker. | stdio |
| MCP_AUTH_TOKEN | No | If set, every HTTP request must send Authorization: Bearer <token>. | |
| KUBESEARCH_CACHE_DIR | No | Where the SQLite databases are cached. In Docker default is /data. | ~/.cache/kubesearch-mcp |
| KUBESEARCH_CLONE_DIR | No | Where ephemeral clones live. | <cacheDir>/clones |
| KUBESEARCH_CLONE_MAX_MB | No | Reject/clean a clone whose tree exceeds this size. | 200 |
| KUBESEARCH_ENABLE_CLONE | No | Enable the repo_* clone/review tools. Set 'false' to hide them entirely. | true |
| KUBESEARCH_REFRESH_HOURS | No | How often to check for a newer daily release. 0 disables refresh. | 24 |
| KUBESEARCH_UPSTREAM_REPO | No | Source repo for the databases (override only for forks/testing). | whazor/k8s-at-home-search |
| KUBESEARCH_CLONE_MAX_REPOS | No | Max concurrent cached clones (LRU-evicted). | 5 |
| KUBESEARCH_CLONE_TTL_MINUTES | No | Auto-delete a clone after this much inactivity. | 30 |
| KUBESEARCH_CLONE_ALLOWED_HOSTS | No | Comma-separated host allowlist. Empty = any public host. | |
| KUBESEARCH_CLONE_ALLOW_PRIVATE | No | Permit cloning from private/loopback/link-local/metadata addresses (SSRF guard off). | false |
| KUBESEARCH_CLONE_TIMEOUT_SECONDS | No | Hard timeout for the git clone subprocess. | 120 |
| KUBESEARCH_CLONE_REFRESH_ON_CLONE | No | On 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
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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 |
| get_releaseA | Get details for one chart by its kubesearch.dev release id (the
|
| 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 |
| 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 |
| repo_list_filesA | List files in a previously cloned repository (by |
| repo_read_fileA | Read a text file from a previously cloned repository (by |
| repo_grepA | Search the text contents of a previously cloned repository (by |
| 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 |
| repo_cleanupA | Delete a temporary clone created by |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| kubesearch_compare_deployments | Compare how the most popular home-ops repos configure a given Helm chart. |
| kubesearch_adopt_chart | Produce a recommended, community-aligned way to deploy a chart. |
| kubesearch_find_config_examples | Find real-world examples of a config key or value across home-ops clusters. |
| kubesearch_pick_image | Find which container image repository and tag the community actually runs for an app. |
| kubesearch_review_repo | Temporarily clone a repository and review its Kubernetes/Flux/Helm setup. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.