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.

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.

Example:

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

get_pod_logs

Retrieve pod logs with sophisticated filtering options.

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.

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:

🔒 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.