{"id":29482604,"url":"https://github.com/kkb0318/kubernetes-mcp","last_synced_at":"2026-01-14T13:11:07.453Z","repository":{"id":300020723,"uuid":"1004948959","full_name":"kkb0318/kubernetes-mcp","owner":"kkb0318","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-27T13:31:27.000Z","size":81,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-11T05:36:49.484Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kkb0318.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T12:27:42.000Z","updated_at":"2025-07-09T10:37:46.000Z","dependencies_parsed_at":"2025-06-19T13:43:37.238Z","dependency_job_id":"10f65514-f215-4ca8-9107-c90669c7c456","html_url":"https://github.com/kkb0318/kubernetes-mcp","commit_stats":null,"previous_names":["kkb0318/kubernetes-mcp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/kkb0318/kubernetes-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkb0318%2Fkubernetes-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkb0318%2Fkubernetes-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkb0318%2Fkubernetes-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkb0318%2Fkubernetes-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkb0318","download_url":"https://codeload.github.com/kkb0318/kubernetes-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkb0318%2Fkubernetes-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28420836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-15T02:01:16.607Z","updated_at":"2026-01-14T13:11:07.435Z","avatar_url":"https://github.com/kkb0318.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Kubernetes MCP Server\n\n[![tests](https://github.com/kkb0318/kubernetes-mcp/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/kkb0318/kubernetes-mcp/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/kkb0318/kubernetes-mcp/graph/badge.svg?token=RPOAC26LAH)](https://codecov.io/gh/kkb0318/kubernetes-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nhttps://github.com/user-attachments/assets/89df70b0-65d1-461c-b4ab-84b2087136fa\n\nA Model Context Protocol (MCP) server that provides safe, read-only access to Kubernetes resources for debugging and inspection. Built with security in mind, it offers comprehensive cluster visibility without modification capabilities.\n\n## Features\n\n- **🔒 Read-only security**: Safely inspect Kubernetes resources without modification capabilities\n- **🎯 CRD support**: Works seamlessly with any Custom Resource Definitions in your cluster\n- **🌐 Multi-cluster support**: Switch between different Kubernetes contexts seamlessly\n- **🔍 Smart discovery**: Find resources by API group substring (e.g., \"flux\" for FluxCD, \"argo\" for ArgoCD)\n- **⚡ High performance**: Efficient resource querying with filtering and pagination\n- **🛠️ Comprehensive toolset**:\n  - `list_resources`: List and filter Kubernetes resources with advanced options\n  - `describe_resource`: Get detailed information about specific resources\n  - `get_pod_logs`: Retrieve pod logs with sophisticated filtering capabilities\n  - `list_events`: List and filter Kubernetes events for debugging and monitoring\n  - `list_contexts`: List all available Kubernetes contexts from kubeconfig\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Kubernetes cluster access with a valid kubeconfig file\n- Go 1.24+ (for building from source)\n\n### Installation Options\n\n#### Option 1: Install with Go (Recommended)\n\n```bash\ngo install github.com/kkb0318/kubernetes-mcp@latest\n```\n\nThe binary will be available at `$GOPATH/bin/kubernetes-mcp` (or `$HOME/go/bin/kubernetes-mcp` if `GOPATH` is not set).\n\n#### Option 2: Build from Source\n\n```bash\ngit clone https://github.com/kkb0318/kubernetes-mcp.git\ncd kubernetes-mcp\ngo build -o kubernetes-mcp .\n```\n\n## ⚙️ Configuration\n\n### MCP Server Setup\n\nAdd the server to your MCP configuration:\n\n#### Basic Configuration\nUses `~/.kube/config` automatically:\n```json\n{\n  \"mcpServers\": {\n    \"kubernetes\": {\n      \"command\": \"/path/to/kubernetes-mcp\"\n    }\n  }\n}\n```\n\n#### Custom Kubeconfig\n```json\n{\n  \"mcpServers\": {\n    \"kubernetes\": {\n      \"command\": \"/path/to/kubernetes-mcp\",\n      \"env\": {\n        \"KUBECONFIG\": \"/path/to/your/kubeconfig\"\n      }\n    }\n  }\n}\n```\n\n\u003e **Note**: Replace `/path/to/kubernetes-mcp` with your actual binary path.\n\n### Standalone Usage\n\n```bash\n# Default kubeconfig (~/.kube/config)\n./kubernetes-mcp\n\n# Custom kubeconfig path\nKUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp\n```\n\n**Important**: Ensure you have appropriate read permissions for the Kubernetes resources you want to inspect.\n\n## 🛠️ Available Tools\n\n### `list_resources`\nList and filter Kubernetes resources with advanced capabilities.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `context` | optional | Kubernetes context name from kubeconfig (leave empty for current context) |\n| `kind` | **required** | Resource type (Pod, Deployment, Service, etc.) or \"all\" for discovery |\n| `groupFilter` | optional | Filter by API group substring for project-specific resources |\n| `namespace` | optional | Target namespace (defaults to all namespaces) |\n| `labelSelector` | optional | Filter by labels (e.g., \"app=nginx\") |\n| `fieldSelector` | optional | Filter by fields (e.g., \"metadata.name=my-pod\") |\n| `limit` | optional | Maximum number of resources to return |\n| `timeoutSeconds` | optional | Request timeout (default: 30s) |\n| `showDetails` | optional | Return full resource objects instead of summary |\n\n**Examples:**\n```json\n// List pods with label selector\n{\n  \"kind\": \"Pod\",\n  \"namespace\": \"default\",\n  \"labelSelector\": \"app=nginx\"\n}\n\n// List pods from a specific cluster context\n{\n  \"kind\": \"Pod\",\n  \"context\": \"production-cluster\",\n  \"namespace\": \"default\"\n}\n\n// Discover FluxCD resources\n{\n  \"kind\": \"all\",\n  \"groupFilter\": \"flux\"\n}\n```\n\n### `describe_resource`\nGet detailed information about a specific Kubernetes resource.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `context` | optional | Kubernetes context name from kubeconfig (leave empty for current context) |\n| `kind` | **required** | Resource type (Pod, Deployment, etc.) |\n| `name` | **required** | Resource name |\n| `namespace` | optional | Target namespace |\n\n**Example:**\n```json\n{\n  \"kind\": \"Pod\",\n  \"name\": \"nginx-pod\",\n  \"namespace\": \"default\"\n}\n```\n\n### `get_pod_logs`\nRetrieve pod logs with sophisticated filtering options.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `context` | optional | Kubernetes context name from kubeconfig (leave empty for current context) |\n| `name` | **required** | Pod name |\n| `namespace` | optional | Pod namespace (defaults to \"default\") |\n| `container` | optional | Specific container name |\n| `tail` | optional | Number of lines from the end (default: 100) |\n| `since` | optional | Duration like \"5s\", \"2m\", \"3h\" |\n| `sinceTime` | optional | RFC3339 timestamp |\n| `timestamps` | optional | Include timestamps in output |\n| `previous` | optional | Get logs from previous container instance |\n\n**Example:**\n```json\n{\n  \"name\": \"nginx-pod\",\n  \"namespace\": \"default\",\n  \"tail\": 50,\n  \"since\": \"5m\",\n  \"timestamps\": true\n}\n```\n\n### `list_events`\nList and filter Kubernetes events with advanced filtering options for debugging and monitoring.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `context` | optional | Kubernetes context name from kubeconfig (leave empty for current context) |\n| `namespace` | optional | Target namespace (leave empty for all namespaces) |\n| `object` | optional | Filter by object name (e.g., pod name, deployment name) |\n| `eventType` | optional | Filter by event type: \"Normal\" or \"Warning\" (case-insensitive) |\n| `reason` | optional | Filter by event reason (e.g., \"Pulled\", \"Failed\", \"FailedScheduling\") |\n| `since` | optional | Duration like \"5s\", \"2m\", \"1h\" |\n| `sinceTime` | optional | RFC3339 timestamp (e.g., \"2025-06-20T10:00:00Z\") |\n| `limit` | optional | Maximum number of events to return (default: 100) |\n| `timeoutSeconds` | optional | Request timeout (default: 30s) |\n\n**Examples:**\n```json\n// List recent warning events\n{\n  \"eventType\": \"Warning\",\n  \"since\": \"30m\"\n}\n\n// List events for a specific pod\n{\n  \"object\": \"nginx-pod\",\n  \"namespace\": \"default\"\n}\n\n// List failed scheduling events\n{\n  \"reason\": \"FailedScheduling\",\n  \"limit\": 50\n}\n```\n\n### `list_contexts`\nList all available Kubernetes contexts from your kubeconfig file.\n\n**Parameters:**\nNone - this tool takes no parameters.\n\n**Example Response:**\n```json\n{\n  \"contexts\": [\n    {\n      \"name\": \"production-cluster\",\n      \"is_current\": false\n    },\n    {\n      \"name\": \"staging-cluster\", \n      \"is_current\": true\n    },\n    {\n      \"name\": \"development-cluster\",\n      \"is_current\": false\n    }\n  ],\n  \"current_context\": \"staging-cluster\",\n  \"total\": 3\n}\n```\n\n**Use Case:**\nPerfect for multi-cluster workflows where you need to:\n- Discover available Kubernetes contexts\n- Identify the current active context\n- Plan operations across multiple clusters\n\n## 🌟 Advanced Features\n\n### 🌐 Multi-Cluster Support\nSeamlessly work with multiple Kubernetes clusters using context switching:\n\n- **Context Parameter**: All tools now support an optional `context` parameter to specify which cluster to query\n- **Automatic Discovery**: Uses your existing kubeconfig file and automatically discovers available contexts\n- **Default Context**: When no context is specified, uses the current context from your kubeconfig\n- **Cached Connections**: Efficiently manages connections to multiple clusters with connection caching\n\n**Multi-cluster Examples:**\n```json\n// Query production cluster\n{\n  \"kind\": \"Pod\",\n  \"context\": \"production-cluster\",\n  \"namespace\": \"default\"\n}\n\n// Get logs from staging environment\n{\n  \"name\": \"api-server\",\n  \"context\": \"staging-cluster\",\n  \"namespace\": \"api\"\n}\n\n// Compare resources across environments (use multiple calls)\n{\n  \"kind\": \"Deployment\",\n  \"context\": \"production-cluster\",\n  \"namespace\": \"app\"\n}\n```\n\n### 🎯 Custom Resource Definition (CRD) Support\nAutomatically discovers and works with any CRDs in your cluster. Simply use the CRD's Kind name with `list_resources` or `describe_resource` tools.\n\n### 🔍 Smart Resource Discovery\nUse the `groupFilter` parameter to discover resources by API group substring:\n\n| Filter | Discovers | Examples |\n|--------|-----------|----------|\n| `\"flux\"` | FluxCD resources | HelmReleases, Kustomizations, GitRepositories |\n| `\"argo\"` | ArgoCD resources | Applications, AppProjects, ApplicationSets |\n| `\"istio\"` | Istio resources | VirtualServices, DestinationRules, Gateways |\n| `\"cert-manager\"` | cert-manager resources | Certificates, Issuers, ClusterIssuers |\n\n### 🔒 Security \u0026 Safety\nBuilt with security as a primary concern:\n- ✅ **Read-only access** - No resource creation, modification, or deletion\n- ✅ **Production safe** - Secure for use in production environments\n- ✅ **Minimal permissions** - Only requires read access to cluster resources\n- ✅ **No destructive operations** - Cannot harm your cluster\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please ensure all changes maintain the read-only nature of the server and include appropriate tests.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkb0318%2Fkubernetes-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkb0318%2Fkubernetes-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkb0318%2Fkubernetes-mcp/lists"}