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 options
  • describe_resource: Get detailed information about specific resources
  • get_pod_logs: Retrieve pod logs with sophisticated filtering capabilities
  • list_events: List and filter Kubernetes events for debugging and monitoring
  • list_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-mcp with 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
context	optional	Kubernetes context name from kubeconfig (leave empty for current context)
kind	required	Resource type (Pod, Deployment, Service, etc.) or "all" for discovery
groupFilter	optional	Filter by API group substring for project-specific resources
namespace	optional	Target namespace (defaults to all namespaces)
labelSelector	optional	Filter by labels (e.g., "app=nginx")
fieldSelector	optional	Filter by fields (e.g., "metadata.name=my-pod")
limit	optional	Maximum number of resources to return
timeoutSeconds	optional	Request timeout (default: 30s)
showDetails	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
context	optional	Kubernetes context name from kubeconfig (leave empty for current context)
kind	required	Resource type (Pod, Deployment, etc.)
name	required	Resource name
namespace	optional	Target namespace

Example:

{
  "kind": "Pod",
  "name": "nginx-pod",
  "namespace": "default"
}

get_pod_logs

Retrieve pod logs with sophisticated filtering options.

Parameter	Type	Description
context	optional	Kubernetes context name from kubeconfig (leave empty for current context)
name	required	Pod name
namespace	optional	Pod namespace (defaults to "default")
container	optional	Specific container name
tail	optional	Number of lines from the end (default: 100)
since	optional	Duration like "5s", "2m", "3h"
sinceTime	optional	RFC3339 timestamp
timestamps	optional	Include timestamps in output
previous	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
context	optional	Kubernetes context name from kubeconfig (leave empty for current context)
namespace	optional	Target namespace (leave empty for all namespaces)
object	optional	Filter by object name (e.g., pod name, deployment name)
eventType	optional	Filter by event type: "Normal" or "Warning" (case-insensitive)
reason	optional	Filter by event reason (e.g., "Pulled", "Failed", "FailedScheduling")
since	optional	Duration like "5s", "2m", "1h"
sinceTime	optional	RFC3339 timestamp (e.g., "2025-06-20T10:00:00Z")
limit	optional	Maximum number of events to return (default: 100)
timeoutSeconds	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 context parameter to specify which cluster to query
• Automatic 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
"flux"	FluxCD resources	HelmReleases, Kustomizations, GitRepositories
"argo"	ArgoCD resources	Applications, AppProjects, ApplicationSets
"istio"	Istio resources	VirtualServices, DestinationRules, Gateways
"cert-manager"	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.