Github

Github

HSn0918

Developer Tools
Visit Server

README

Kubernetes MCP

<div align="center"> <img src="logo.png" alt="Kubernetes MCP Logo" width="200"> </div>

English | 中文

✨ A Model Context Protocol (MCP) server implementation designed with Go for interacting with Kubernetes clusters. This server allows MCP-compatible clients to perform Kubernetes operations through defined tools.

📌 Core Features

  • 🔹 MCP Server: Implements the mcp-go library to provide MCP functionality
  • 🔹 Kubernetes Interaction: Uses controller-runtime client to interact with clusters
  • 🔹 Transport Methods: Supports standard I/O (stdio) or Server-Sent Events (sse)// but the stdio is not implement

🛠️ Resource Management Tools

📊 Implemented API Groups

🔸 Core API Group (v1)

  • List, get, describe, create, update, delete operations
  • Cluster-scoped: list namespaces, list nodes
  • Get Pod logs functionality

🔸 Apps API Group (apps/v1)

  • Full support for Deployment, ReplicaSet, StatefulSet, DaemonSet

🔸 Batch API Group (batch/v1)

  • Full support for Job, CronJob

🔸 Networking API Group (networking.k8s.io/v1)

  • Full support for Ingress, NetworkPolicy

🔸 RBAC API Group (rbac.authorization.k8s.io/v1)

  • Full support for Role, RoleBinding, ClusterRole, ClusterRoleBinding

🔸 Storage API Group (storage.k8s.io/v1)

  • Full support for StorageClass, VolumeAttachment

🔸 Policy API Group (policy/v1beta1)

  • Full support for PodSecurityPolicy, PodDisruptionBudget

🔸 API Extensions API Group (apiextensions.k8s.io/v1)

  • Full support for CustomResourceDefinition

🔸 Autoscaling API Group (autoscaling/v1)

  • Full support for HorizontalPodAutoscaler

📋 Requirements

  • 📌 Go 1.24
  • 📌 Kubernetes cluster access (via kubeconfig or in-cluster service account)

📦 Key Dependencies

🧩 Core Libraries:

  • github.com/mark3labs/mcp-go - MCP protocol implementation
  • sigs.k8s.io/controller-runtime - Kubernetes client
  • k8s.io/client-go - Core Kubernetes libraries
  • github.com/spf13/cobra - CLI structure
  • go.uber.org/zap - Logging
  • sigs.k8s.io/yaml - YAML processing

🔨 Build Methods

📥 Build from Source

git clone https://github.com/HSn0918/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp ./cmd/kubernetes-mcp
./kubernetes-mcp server --transport=sse --port 8080

🐳 Docker Build

# Build image
docker build -t kubernetes-mcp:latest \
  --build-arg VERSION=$(git describe --tags --always) \
  --build-arg COMMIT=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") .

# Run with stdio transport
docker run -v ~/.kube:/root/.kube kubernetes-mcp:latest server transport stdio

# Run with SSE transport
docker run -p 8080:8080 -v ~/.kube:/root/.kube kubernetes-mcp:latest server transport sse

# Run with SSE transport and custom base URL
docker run -p 8080:8080 -v ~/.kube:/root/.kube kubernetes-mcp:latest server transport sse --base-url="http://your-host:8080"

# View version info
docker run kubernetes-mcp:latest version

# Specify custom kubeconfig
docker run -v /path/to/config:/config kubernetes-mcp:latest server transport sse --kubeconfig=/config

🚀 Usage

🔄 Starting the Server

# Using standard I/O
./kubernetes-mcp server transport stdio

# Using SSE (Server-Sent Events)
./kubernetes-mcp server transport sse --port 8080

# Specifying custom base URL for SSE connections
./kubernetes-mcp server transport sse --port 8080 --base-url="http://your-server-address:8080"

# Setting CORS allowed origins
./kubernetes-mcp server transport sse --allow-origins="*"

# Specifying Kubeconfig
./kubernetes-mcp server transport sse --kubeconfig /path/to/your/kubeconfig

# View version
./kubernetes-mcp version

⚙️ Command Structure

The application uses a hierarchical command structure:

kubernetes-mcp
├── server
│   └── transport
│       ├── sse
│       │   ├── --port=8080
│       │   ├── --health-port=8081
│       │   ├── --base-url="http://example.com:8080"
│       │   └── --allow-origins="*"
│       └── stdio
└── version

⚙️ Configuration Options

Global options that can be used with any command:

  • 🔧 Config file: --kubeconfig (path to Kubernetes configuration)
  • 🔧 Log level: --log-level (debug/info/warn/error)
  • 🔧 Log format: --log-format (console/json)

SSE transport specific options:

  • 🔧 Port: --port (default 8080)
  • 🔧 Health check port: --health-port (default 8081)
  • 🔧 Base URL: --base-url (URL clients will use to connect to the server)
  • 🔧 CORS allowed origins: --allow-origins (comma-separated list or "*" for all)

🧩 Advanced Features

🔍 Structured Tools

  • 🔍 GET_CLUSTER_INFO: Get cluster information and version details
  • 🔍 GET_API_RESOURCES: List available API resources in the cluster
  • 🔍 SEARCH_RESOURCES: Search across namespaces and resource types
  • 🔍 EXPLAIN_RESOURCE: Get resource structure and field details
  • 🔍 APPLY_MANIFEST: Apply YAML manifests to the cluster
  • 🔍 VALIDATE_MANIFEST: Validate YAML manifest format
  • 🔍 DIFF_MANIFEST: Compare YAML with existing cluster resources
  • 🔍 GET_EVENTS: Get events related to specific resources

💡 Prompt System

  • 🔖 KUBERNETES_YAML_PROMPT: Generate standard Kubernetes YAML
  • 🔖 KUBERNETES_QUERY_PROMPT: Kubernetes operation guidance
  • 🔖 TROUBLESHOOT_PODS_PROMPT: Pod troubleshooting guide
  • 🔖 TROUBLESHOOT_NODES_PROMPT: Node troubleshooting guide

🔄 Standard Resource Operations

Each API group supports the following operations:

  • List resources: Get resource lists, filterable by namespace and labels
  • Get resource: Retrieve specific resources in YAML format
  • Describe resource: Get detailed readable descriptions of resources
  • Create resource: Create new resources from YAML
  • Update resource: Update existing resources using YAML
  • Delete resource: Remove specific resources

🌟 Core API Group Special Operations

  • Get Pod logs: Retrieve logs from specific Pod containers
  • List namespaces: View all available namespaces in the cluster
  • List nodes: View all nodes and their status in the cluster

📊 Log Analysis Features

  • Error Pattern Recognition: Identifies common error patterns and frequencies
  • Time-based Distribution Analysis: Analyzes error occurrence patterns over time
  • HTTP Status Code Tracking: Monitors and categorizes HTTP response codes
  • Performance Metrics: Tracks response times and resource usage statistics

📊 Cluster Metrics Features

  • 🔍 GET_NODE_METRICS: Retrieve node resource usage metrics, including CPU and memory utilization
  • 🔍 GET_POD_METRICS: Get Pod resource usage metrics to monitor container CPU and memory consumption
  • 🔍 GET_RESOURCE_METRICS: Obtain overall cluster resource usage including CPU, memory, storage, and Pod count statistics
  • 🔍 GET_TOP_CONSUMERS: Identify Pods with highest resource consumption to pinpoint resource bottlenecks

All metrics APIs support:

  • Flexible sorting: Sort by CPU, memory consumption or utilization percentage
  • Detailed filtering: Use field selectors and label selectors to target resources precisely
  • Result limitation: Control the number of returned results
  • JSON formatting: All responses are returned in structured JSON format for easy processing

📝 Cluster Metrics Prompt System

  • 🔖 CLUSTER_RESOURCE_USAGE: Guidance for retrieving cluster resource usage
  • 🔖 NODE_RESOURCE_USAGE: Guidance for retrieving node resource usage
  • 🔖 POD_RESOURCE_USAGE: Guidance for retrieving Pod resource usage

📋 API Response Formatting

All API responses are now standardized in JSON format:

  • 🔸 Structured Responses: All API responses are returned in consistent JSON structures
  • 🔸 Node Lists: Include detailed information such as node name, status, roles, labels, taints, and allocatable resources
  • 🔸 Namespace Lists: Include namespace name, status, labels, annotations, and other details
  • 🔸 Logs and Log Analysis: Log content and analysis results are returned in structured format for easy processing
  • 🔸 Resource Metrics: CPU, memory, storage metrics are returned in structured format including raw values and percentages
  • 🔸 Time Formatting: Supports human-readable time formats in both English and Chinese, such as "5 minutes ago"/"5分钟前"

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
MCP Package Docs Server

MCP Package Docs Server

Facilitates LLMs to efficiently access and fetch structured documentation for packages in Go, Python, and NPM, enhancing software development with multi-language support and performance optimization.

Featured
Local
TypeScript
Claude Code MCP

Claude Code MCP

An implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.

Featured
Local
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

Model Context Protocol server for Task Management. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system.

Featured
Local
JavaScript
Linear MCP Server

Linear MCP Server

Enables interaction with Linear's API for managing issues, teams, and projects programmatically through the Model Context Protocol.

Featured
JavaScript
mermaid-mcp-server

mermaid-mcp-server

A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.

Featured
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP server to provide Jira Tickets information to AI coding agents like Cursor

Featured
TypeScript
Linear MCP Server

Linear MCP Server

A Model Context Protocol server that integrates with Linear's issue tracking system, allowing LLMs to create, update, search, and comment on Linear issues through natural language interactions.

Featured
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

This server facilitates structured problem-solving by breaking down complex issues into sequential steps, supporting revisions, and enabling multiple solution paths through full MCP integration.

Featured
Python