-
security-
license-
qualityMCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.
Last updated -
3
4
MIT License
Supports discovery and inspection of ArgoCD resources including Applications, AppProjects, and ApplicationSets via the smart resource discovery functionality.
Enables discovery and inspection of FluxCD resources such as HelmReleases, Kustomizations, and GitRepositories through the smart discovery feature.
Supports inspection of Helm-related resources in the cluster, particularly when used with FluxCD's HelmReleases.
Facilitates discovery and inspection of Istio resources such as VirtualServices, DestinationRules, and Gateways through the groupFilter parameter.
Provides read-only access to Kubernetes resources, allowing users to list resources, describe specific objects, retrieve pod logs, and monitor events for debugging and inspection purposes without modification capabilities.
Kubernetes MCP Server
https://github.com/user-attachments/assets/89df70b0-65d1-461c-b4ab-84b2087136fa
A 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.
Features
🔒 Read-only security: Safely inspect Kubernetes resources without modification capabilities
🎯 CRD support: Works seamlessly with any Custom Resource Definitions in your cluster
🌐 Multi-cluster support: Switch between different Kubernetes contexts seamlessly
🔍 Smart discovery: Find resources by API group substring (e.g., "flux" for FluxCD, "argo" for ArgoCD)
⚡ High performance: Efficient resource querying with filtering and pagination
🛠️ Comprehensive toolset:
list_resources: List and filter Kubernetes resources with advanced optionsdescribe_resource: Get detailed information about specific resourcesget_pod_logs: Retrieve pod logs with sophisticated filtering capabilitieslist_events: List and filter Kubernetes events for debugging and monitoringlist_contexts: List all available Kubernetes contexts from kubeconfig
🚀 Quick Start
Prerequisites
Kubernetes cluster access with a valid kubeconfig file
Go 1.24+ (for building from source)
Installation Options
Option 1: Install with Go (Recommended)
go install github.com/kkb0318/kubernetes-mcp@latest
The binary will be available at $GOPATH/bin/kubernetes-mcp (or $HOME/go/bin/kubernetes-mcp if GOPATH is not set).
Option 2: Build from Source
git clone https://github.com/kkb0318/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp .
⚙️ Configuration
MCP Server Setup
Add the server to your MCP configuration:
Basic Configuration
Uses ~/.kube/config automatically:
{
"mcpServers": {
"kubernetes": {
"command": "/path/to/kubernetes-mcp"
}
}
}
Custom Kubeconfig
{
"mcpServers": {
"kubernetes": {
"command": "/path/to/kubernetes-mcp",
"env": {
"KUBECONFIG": "/path/to/your/kubeconfig"
}
}
}
}
Note: Replace
/path/to/kubernetes-mcpwith your actual binary path.
Standalone Usage
# Default kubeconfig (~/.kube/config)
./kubernetes-mcp
# Custom kubeconfig path
KUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp
Important: Ensure you have appropriate read permissions for the Kubernetes resources you want to inspect.
🛠️ Available Tools
list_resources
List and filter Kubernetes resources with advanced capabilities.
Parameter | Type | Description |
| optional | Kubernetes context name from kubeconfig (leave empty for current context) |
| required | Resource type (Pod, Deployment, Service, etc.) or "all" for discovery |
| optional | Filter by API group substring for project-specific resources |
| optional | Target namespace (defaults to all namespaces) |
| optional | Filter by labels (e.g., "app=nginx") |
| optional | Filter by fields (e.g., "metadata.name=my-pod") |
| optional | Maximum number of resources to return |
| optional | Request timeout (default: 30s) |
| optional | Return full resource objects instead of summary |
Examples:
// List pods with label selector
{
"kind": "Pod",
"namespace": "default",
"labelSelector": "app=nginx"
}
// List pods from a specific cluster context
{
"kind": "Pod",
"context": "production-cluster",
"namespace": "default"
}
// Discover FluxCD resources
{
"kind": "all",
"groupFilter": "flux"
}
describe_resource
Get detailed information about a specific Kubernetes resource.
Parameter | Type | Description |
| optional | Kubernetes context name from kubeconfig (leave empty for current context) |
| required | Resource type (Pod, Deployment, etc.) |
| required | Resource name |
| optional | Target namespace |
Example:
{
"kind": "Pod",
"name": "nginx-pod",
"namespace": "default"
}
get_pod_logs
Retrieve pod logs with sophisticated filtering options.
Parameter | Type | Description |
| optional | Kubernetes context name from kubeconfig (leave empty for current context) |
| required | Pod name |
| optional | Pod namespace (defaults to "default") |
| optional | Specific container name |
| optional | Number of lines from the end (default: 100) |
| optional | Duration like "5s", "2m", "3h" |
| optional | RFC3339 timestamp |
| optional | Include timestamps in output |
| optional | Get logs from previous container instance |
Example:
{
"name": "nginx-pod",
"namespace": "default",
"tail": 50,
"since": "5m",
"timestamps": true
}
list_events
List and filter Kubernetes events with advanced filtering options for debugging and monitoring.
Parameter | Type | Description |
| optional | Kubernetes context name from kubeconfig (leave empty for current context) |
| optional | Target namespace (leave empty for all namespaces) |
| optional | Filter by object name (e.g., pod name, deployment name) |
| optional | Filter by event type: "Normal" or "Warning" (case-insensitive) |
| optional | Filter by event reason (e.g., "Pulled", "Failed", "FailedScheduling") |
| optional | Duration like "5s", "2m", "1h" |
| optional | RFC3339 timestamp (e.g., "2025-06-20T10:00:00Z") |
| optional | Maximum number of events to return (default: 100) |
| optional | Request timeout (default: 30s) |
Examples:
// List recent warning events
{
"eventType": "Warning",
"since": "30m"
}
// List events for a specific pod
{
"object": "nginx-pod",
"namespace": "default"
}
// List failed scheduling events
{
"reason": "FailedScheduling",
"limit": 50
}
list_contexts
List all available Kubernetes contexts from your kubeconfig file.
Parameters: None - this tool takes no parameters.
Example Response:
{
"contexts": [
{
"name": "production-cluster",
"is_current": false
},
{
"name": "staging-cluster",
"is_current": true
},
{
"name": "development-cluster",
"is_current": false
}
],
"current_context": "staging-cluster",
"total": 3
}
Use Case: Perfect for multi-cluster workflows where you need to:
Discover available Kubernetes contexts
Identify the current active context
Plan operations across multiple clusters
🌟 Advanced Features
🌐 Multi-Cluster Support
Seamlessly work with multiple Kubernetes clusters using context switching:
Context Parameter: All tools now support an optional
contextparameter to specify which cluster to queryAutomatic Discovery: Uses your existing kubeconfig file and automatically discovers available contexts
Default Context: When no context is specified, uses the current context from your kubeconfig
Cached Connections: Efficiently manages connections to multiple clusters with connection caching
Multi-cluster Examples:
// Query production cluster
{
"kind": "Pod",
"context": "production-cluster",
"namespace": "default"
}
// Get logs from staging environment
{
"name": "api-server",
"context": "staging-cluster",
"namespace": "api"
}
// Compare resources across environments (use multiple calls)
{
"kind": "Deployment",
"context": "production-cluster",
"namespace": "app"
}
🎯 Custom Resource Definition (CRD) Support
Automatically discovers and works with any CRDs in your cluster. Simply use the CRD's Kind name with list_resources or describe_resource tools.
🔍 Smart Resource Discovery
Use the groupFilter parameter to discover resources by API group substring:
Filter | Discovers | Examples |
| FluxCD resources | HelmReleases, Kustomizations, GitRepositories |
| ArgoCD resources | Applications, AppProjects, ApplicationSets |
| Istio resources | VirtualServices, DestinationRules, Gateways |
| cert-manager resources | Certificates, Issuers, ClusterIssuers |
🔒 Security & Safety
Built with security as a primary concern:
✅ Read-only access - No resource creation, modification, or deletion
✅ Production safe - Secure for use in production environments
✅ Minimal permissions - Only requires read access to cluster resources
✅ No destructive operations - Cannot harm your cluster
🤝 Contributing
We welcome contributions! Please ensure all changes maintain the read-only nature of the server and include appropriate tests.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A 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.
Related MCP Servers
- -security-license-qualityMCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.Last updated -63MIT License
- -security-license-qualityA Kubernetes-deployed server for the Model Context Protocol that enables secure communication with configurable environment variables, health monitoring, and scalable deployment on Azure Kubernetes Service.
- GoMIT License