Are you the author? Sign in to claim
MCP server providing tools for searching https://kubesearch.dev/
An MCP (Model Context Protocol) server that provides tools to query k8s-at-home-search for real-world Helm deployment examples from the Kubernetes homelab community.
This MCP server queries a local k8s-at-home-search SQLite database containing:
Pull and run the pre-built image from GitHub Container Registry:
# Pull the latest image
docker pull ghcr.io/rust84/kubesearch-mcp-server:latest
# Run with database volumes (REQUIRED)
docker run --init -i \
-v $(pwd)/repos.db:/data/repos.db:ro \
-v $(pwd)/repos-extended.db:/data/repos-extended.db:ro \
ghcr.io/rust84/kubesearch-mcp-server:latest
Important: The Docker image does NOT include databases. You must mount your database files at /data/repos.db and /data/repos-extended.db.
Add to your Claude Desktop configuration (~/.config/Claude/claude_desktop_config.json):
{
"mcpServers": {
"kubesearch": {
"command": "docker",
"args": [
"run",
"--init",
"-i",
"--rm",
"-v",
"/absolute/path/to/repos.db:/data/repos.db:ro",
"-v",
"/absolute/path/to/repos-extended.db:/data/repos-extended.db:ro",
"ghcr.io/rust84/kubesearch-mcp-server:latest"
]
}
}
}
Note: Replace /absolute/path/to/ with the actual absolute path to your database files.
# Build the image
docker build -t kubesearch-mcp-server .
# Run your local build
docker run --init -i \
-v $(pwd)/repos.db:/data/repos.db:ro \
-v $(pwd)/repos-extended.db:/data/repos-extended.db:ro \
kubesearch-mcp-server
The container requires two SQLite database files to be mounted:
Mount location: /data/
These files are NOT included in the Docker image. You must:
Configure the server using environment variables:
KUBESEARCH_DB_PATH - Path to main database (default: /data/repos.db)KUBESEARCH_DB_EXTENDED_PATH - Path to extended database (default: /data/repos-extended.db)AUTHOR_WEIGHTS - JSON object for author scoring (default: {"bjw-s": 1.5})Example with custom environment:
docker run --init -i \
-e 'AUTHOR_WEIGHTS={"bjw-s": 1.5, "onedr0p": 1.2}' \
-v $(pwd)/repos.db:/data/repos.db:ro \
-v $(pwd)/repos-extended.db:/data/repos-extended.db:ro \
kubesearch-mcp-server
The image supports both AMD64 and ARM64 architectures:
# Pull specific platform
docker pull --platform linux/amd64 ghcr.io/rust84/kubesearch-mcp-server:latest
docker pull --platform linux/arm64 ghcr.io/rust84/kubesearch-mcp-server:latest
Works on:
repos.db - Main database with release and repository metadatarepos-extended.db - Extended database with Helm valuesOption 1: Download pre-built databases (Recommended)
Use the included download script to fetch the latest databases from GitHub releases:
# Download to current directory
./download-databases.sh
# Or use npm script
npm run download-db
# Or specify custom directory
DOWNLOAD_DIR=/path/to/databases ./download-databases.sh
Requirements:
wget or curl (usually pre-installed)jq - Install with: sudo apt-get install jq (Ubuntu/Debian) or brew install jq (macOS)The script will download:
repos.db (~5.7 MB) - Main databaserepos-extended.db (~29.8 MB) - Extended databaseOption 2: Build from source
Clone and build the k8s-at-home-search project:
git clone https://github.com/whazor/k8s-at-home-search
cd k8s-at-home-search
# Follow their build instructions to generate the databases
# The databases will be created at:
# repos.db (5.7 MB)
# repos-extended.db (29.8 MB)
# Clone this repository
git clone <repository-url>
cd kubesearch-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
The server requires two environment variables to point to your local k8s-at-home-search databases:
export KUBESEARCH_DB_PATH=/path/to/k8s-at-home-search/repos.db
export KUBESEARCH_DB_EXTENDED_PATH=/path/to/k8s-at-home-search/repos-extended.db
AUTHOR_WEIGHTS - JSON object with author boost multipliers (see below)You can customize which chart authors get boosted in search results by setting the AUTHOR_WEIGHTS environment variable with a JSON object:
Default weights (if not specified):
{
"bjw-s": 1.5
}
Examples:
# Boost bjw-s charts by 100%
AUTHOR_WEIGHTS='{"bjw-s": 2.0}'
# Boost multiple authors
AUTHOR_WEIGHTS='{"bjw-s": 1.1, "ondr0p": 1.1}'
# Disable all author boosts
AUTHOR_WEIGHTS='{}'
# Custom weights
AUTHOR_WEIGHTS='{"my-favorite-author": 1.5}'
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Basic configuration:
{
"mcpServers": {
"kubesearch": {
"command": "node",
"args": ["/absolute/path/to/kubesearch-mcp-server/dist/index.js"],
"env": {
"KUBESEARCH_DB_PATH": "/home/russell/repos/k8s-at-home-search/repos.db",
"KUBESEARCH_DB_EXTENDED_PATH": "/home/russell/repos/k8s-at-home-search/repos-extended.db"
}
}
}
}
With custom author weights:
{
"mcpServers": {
"kubesearch": {
"command": "node",
"args": ["/absolute/path/to/kubesearch-mcp-server/dist/index.js"],
"env": {
"KUBESEARCH_DB_PATH": "/home/russell/repos/k8s-at-home-search/repos.db",
"KUBESEARCH_DB_EXTENDED_PATH": "/home/russell/repos/k8s-at-home-search/repos-extended.db",
"AUTHOR_WEIGHTS": "{\"bjw-s\": 1.1, \"onedr0p\": 1.1, \"billimek\": 1.1}"
}
}
}
}
Note: In JSON, you must escape quotes with \". The value "AUTHOR_WEIGHTS": "{\"bjw-s\": 1.5}" becomes {"bjw-s": 1.5} when parsed.
For other MCP-compatible clients, use the stdio transport with the compiled server:
node /path/to/kubesearch-mcp-server/dist/index.js
search_deploymentsSearch for real-world deployment examples from community repositories. Returns individual deployments showing how users configure and deploy Helm charts, ranked by repository quality (stars) and author reputation. Use this to find example configurations to learn from.
Parameters:
query (string, required) - Chart or release name (e.g., "plex", "traefik")limit (number, optional) - Max results to return (default: 10, max: 100)Example:
{
"query": "radarr",
"limit": 3
}
Returns individual deployments:
[
{
"name": "radarr",
"chart": "radarr",
"helmRepoURL": "oci://ghcr.io/bjw-s-labs/helm/app-template",
"repo": "onedr0p/home-ops",
"repoUrl": "https://github.com/onedr0p/home-ops",
"stars": 2670,
"version": "4.5.0",
"deploymentUrl": "https://github.com/onedr0p/home-ops/.../radarr.yaml",
"key": "ghcr.io-bjw-s-labs-helm-app-template-radarr",
"score": 304.7
}
]
list_chart_sourcesList all available chart sources (helm repositories) for a given chart name with deployment counts. Compare official repos vs mirrors vs community forks to choose the most popular/reliable source.
Parameters:
query (string, required) - Chart or release name to search for (e.g., "openebs", "plex")minCount (number, optional) - Minimum number of repositories required to include a chart (default: 3)Examples:
// Find all chart paths for "openebs"
{
"query": "openebs",
"minCount": 3
}
// Include even rarely-used charts
{
"query": "plex",
"minCount": 1
}
Returns:
[
{
"name": "openebs",
"chart": "openebs",
"helmRepoURL": "oci://ghcr.io/home-operations/charts-mirror/openebs",
"key": "ghcr.io-home-operations-charts-mirror-openebs-openebs",
"count": 74,
"icon": null
},
{
"name": "openebs",
"chart": "openebs",
"helmRepoURL": "https://openebs.github.io/openebs",
"key": "openebs.github.io-openebs-openebs-openebs",
"count": 47,
"icon": null
}
]
Use cases:
get_chart_detailsGet detailed information about a specific Helm chart including repositories using it and popular configuration values.
Parameters:
key (string, required) - Chart key from search resultsincludeValues (boolean, optional) - Include values analysis (default: true)valuesLimit (number, optional) - Max value variations per path (default: 5, max: 10)pathsLimit (number, optional) - Max configuration paths to return (default: 15, max: 50)valuePath (string, optional) - Filter to specific configuration path prefix (e.g., "persistence")Examples:
// Get all chart details
{
"key": "ghcr.io-bjw-s-helm-plex",
"includeValues": true
}
// Filter to only persistence-related configurations
{
"key": "ghcr.io-bjw-s-helm-plex",
"valuePath": "persistence",
"valuesLimit": 5
}
// Focus on ingress settings
{
"key": "ghcr.io-bjw-s-helm-traefik",
"valuePath": "ingress"
}
// Get more paths and values (within limits)
{
"key": "ghcr.io-bjw-s-helm-plex",
"pathsLimit": 20,
"valuesLimit": 10
}
Important - Avoiding Token Limits:
valuePath: "persistence") can return large resultsget_chart_index first to explore available pathsvaluePath: "persistence.incomplete")valuesLimit low (5 or less) for exploratory queriesvaluesLimit max 10, pathsLimit max 50Returns:
get_chart_indexExplore what configuration paths are available in a chart by listing all paths found across real-world deployments. This helps discover what settings can be configured before diving into the actual values.
Parameters:
key (string, required) - Chart key from search resultssearchPath (string, optional) - Filter to paths starting with this prefix (e.g., "persistence")Examples:
// List all available configuration paths
{
"key": "ghcr.io-bjw-s-helm-plex"
}
// Explore only persistence-related paths
{
"key": "ghcr.io-bjw-s-helm-plex",
"searchPath": "persistence"
}
// See what ingress configurations are available
{
"key": "ghcr.io-bjw-s-helm-traefik",
"searchPath": "ingress"
}
Returns:
{
"name": "plex",
"chartName": "plex",
"totalDeployments": 25,
"paths": [
{
"path": "persistence.config.enabled",
"usageCount": 25
},
{
"path": "persistence.config.existingClaim",
"usageCount": 24
},
{
"path": "persistence.media.enabled",
"usageCount": 23
},
{
"path": "persistence.media.type",
"usageCount": 20
}
]
}
Use cases:
searchPath: "persistence"searchPath: "ingress"get_chart_detailsget_chart_statsGet statistics and metrics about a specific Helm chart source including deployment count, repository quality metrics (stars), version distribution, and top repositories. Requires a chart key from list_chart_sources or search_deployments.
Parameters:
key (string, required) - Chart key (e.g., "ghcr.io-home-operations-charts-mirror-openebs-openebs")Examples:
// Get stats for a specific chart source
{
"key": "ghcr.io-bjw-s-helm-plex"
}
// Typical workflow: first list sources, then get stats
// 1. Use list_chart_sources to find: key = "ghcr.io-home-operations-charts-mirror-openebs-openebs"
// 2. Then get stats for that specific source:
{
"key": "ghcr.io-home-operations-charts-mirror-openebs-openebs"
}
Returns:
{
"name": "plex",
"chartName": "app-template",
"helmRepoURL": "oci://ghcr.io/bjw-s-labs/helm/app-template",
"helmRepoName": "app-template",
"icon": "plex.png",
"statistics": {
"totalDeployments": 67,
"minStars": 0,
"maxStars": 2670,
"latestVersion": "4.5.0"
},
"topRepositories": [
{
"repo": "onedr0p/home-ops",
"repoUrl": "https://github.com/onedr0p/home-ops",
"stars": 2670,
"version": "4.5.0"
},
{
"repo": "billimek/k8s-gitops",
"repoUrl": "https://github.com/billimek/k8s-gitops",
"stars": 748,
"version": "4.5.0"
}
],
"versionDistribution": [
{
"version": "4.5.0",
"count": 45
},
{
"version": "3.2.0",
"count": 12
},
{
"version": "3.1.0",
"count": 10
}
]
}
Use cases:
search_container_imagesFind deployments using specific container images.
Parameters:
image (string, required) - Image repository to search forlimit (number, optional) - Max results (default: 20)Example:
{
"image": "ghcr.io/linuxserver/plex",
"limit": 5
}
Returns:
[
{
"repository": "ghcr.io/linuxserver/plex",
"tags": [
{
"tag": "latest",
"usageCount": 45,
"deployments": [
{
"repoName": "user/k8s-cluster",
"repoUrl": "https://github.com/..."
}
]
}
]
}
]
# With tsx watch mode
npm run watch
# Or with tsx dev mode
npm run dev
The project uses Vitest for unit and integration testing.
Run tests:
# Run tests once
npm test
# Run tests in watch mode (re-runs on file changes)
npm run test:watch
# Generate coverage report
npm run test:coverage
# Open interactive test UI in browser
npm run test:ui
Testing approach:
src/test/fixtures.tsCI/CD: Tests run automatically on every push and pull request via GitHub Actions. Coverage reports are generated and enforced (80% minimum threshold).
kubesearch-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── tool-handler.ts # Tool registration and dispatch
│ ├── tool-inputs.ts # Shared input schema helpers
│ ├── types/
│ │ └── kubesearch.ts # Type definitions
│ ├── services/
│ │ ├── database.ts # SQLite connection manager
│ │ └── data-collector.ts # SQL queries and data aggregation
│ ├── tools/
│ │ ├── search-deployments.ts
│ │ ├── list-chart-sources.ts
│ │ ├── get-chart-details.ts
│ │ ├── get-chart-index.ts
│ │ ├── get-chart-stats.ts
│ │ └── search-container-images.ts
│ ├── utils/
│ │ ├── scoring.ts # Search scoring algorithm
│ │ └── semver.ts # Semantic version parsing/comparison
│ └── test/ # Shared fixtures and integration-test helpers
├── dist/ # Compiled JavaScript (generated)
├── package.json
└── tsconfig.json
The search scoring algorithm ranks individual deployments based on repository quality and author reputation:
baseScore = fullMatchScore - lengthScore + starsScore;
finalScore = baseScore * authorMultiplier;
// fullMatchScore: 100 if exact match
// lengthScore: (name.length - query.length) * 1
// starsScore: stars * 0.1 (individual repository quality)
// authorMultiplier: configurable per repository owner (default: bjw-s 1.5)
Scoring Components:
Important: Author boost applies to the repository owner (e.g., onedr0p, bjw-s), not the chart maintainer.
Example: "radarr" search results
onedr0p/home-ops (2670 stars):
bjw-s/home-ops (395 stars):
billimek/k8s-gitops (748 stars):
Stars Impact:
Author Weighting:
AUTHOR_WEIGHTS environment variable{"bjw-s": 1.5}Ensure the database paths are correct and the files exist:
ls -lh /path/to/repos.db
ls -lh /path/to/repos-extended.db
Check file permissions - the server needs read access to both database files.
The databases may be empty or out of date. Rebuild the k8s-at-home-search databases following their documentation.
This project uses semantic versioning and automated releases via GitHub Actions.
Every release produces multi-platform Docker images published to GitHub Container Registry:
# Pull specific version
docker pull ghcr.io/rust84/kubesearch-mcp-server:1.0.1
# Pull latest stable
docker pull ghcr.io/rust84/kubesearch-mcp-server:latest
# Pull by major version (gets latest 1.x.x)
docker pull ghcr.io/rust84/kubesearch-mcp-server:1
# Pull by major.minor version (gets latest 1.0.x)
docker pull ghcr.io/rust84/kubesearch-mcp-server:1.0
Available tags:
latest - Latest stable release from main branch1.2.3 - Specific version (semantic versioning)1.2 - Latest patch version for minor release1 - Latest minor/patch version for major releaseView all releases: GitHub Releases
Releases are automated when you create and push a version tag:
Update version and create tag:
npm version patch # or minor, or major
This automatically:
package.json and package-lock.jsonv0.0.2)Push commit and tag:
git push --follow-tags
GitHub Actions automatically:
v*.*.*)Review and verify (typically completes in 10-15 minutes):
docker pull ghcr.io/rust84/kubesearch-mcp-server:0.0.2For beta or alpha releases:
# Set pre-release version
npm version 1.0.1-beta.1
# Push commit and tag
git push --follow-tags
Pre-release tags (with -beta, -alpha, etc.) create GitHub pre-releases that are not marked as "latest".
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows