mcp-server-kubernetes
by: Flux159
MCP Server for kubernetes management commands
📌Overview
Purpose: The MCP Server Kubernetes is designed to connect and manage a Kubernetes cluster seamlessly.
Overview: This framework serves as an interface to facilitate interactions with Kubernetes clusters. By leveraging standard tools like kubectl and Helm, it enables users to perform a variety of cluster management tasks through a simple command-line interface.
Key Features:
-
Kubernetes Cluster Connectivity: Automatically connects to the current kubectl context for streamlined operations.
-
Resource Management: Allows users to list, create, delete, and describe various Kubernetes resources, including pods, services, deployments, and namespaces.
-
Helm Support: Integrates Helm v3 for managing chart installations, upgrades, and custom configurations within the Kubernetes environment.
-
Real-time Log Access: Supports fetching logs from pods for troubleshooting and includes features to observe Kubernetes events.
-
Port Forwarding: Facilitates port forwarding to specific pods or services, enhancing accessibility for user applications.
MCP Server Kubernetes
MCP Server that can connect to a Kubernetes cluster and manage it.
Usage with Claude Desktop
{
"mcpServers": {
"kubernetes": {
"command": "npx",
"args": ["mcp-server-kubernetes"]
}
}
}
The server will automatically connect to your current kubectl context. Ensure you have:
- kubectl installed and in your PATH
- A valid kubeconfig file with contexts configured
- Access to a Kubernetes cluster configured for kubectl (e.g. minikube, Rancher Desktop, GKE, etc.)
- Helm v3 installed and in your PATH (optional if you don't plan to use Helm)
Verify your connection by asking Claude to list your pods or create a test deployment.
If you encounter errors, open a terminal and run kubectl get pods
to check cluster connectivity and credentials.
Usage with mcp-chat
mcp-chat is a CLI chat client for MCP servers. Use it to interact with the Kubernetes server:
npx mcp-chat --server "npx mcp-server-kubernetes"
Alternatively, pass your existing Claude Desktop configuration file:
Mac:
npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"
Windows:
npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
Features
- Connect to a Kubernetes cluster
- List all pods, services, deployments
- List and describe nodes
- Create, describe, delete pods
- List all namespaces, create namespaces
- Create custom pod & deployment configs, update deployment replicas
- Create, describe, delete, update services
- Manage ConfigMaps (create, get, update, delete)
- Get logs from pods for debugging (pods, deployments, jobs, label selectors)
- Helm v3 support for installing charts
- Install charts with custom values
- Uninstall releases
- Upgrade releases
- Support namespaces, version specification, custom repositories
- kubectl explain and kubectl api-resources support
- Retrieve Kubernetes events from the cluster
- Port forward to pods or services
- Create, list, and describe cronjobs
- Non-destructive mode for read and create/update-only cluster access
Local Development
Make sure you have bun installed. Then clone the repository and install dependencies:
git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install
Development Workflow
- Start the server in development mode (watches for file changes):
bun run dev
- Run unit tests:
bun run test
- Build the project:
bun run build
- Local Testing with Inspector
npx @modelcontextprotocol/inspector node dist/index.js
# Follow terminal instructions for Inspector link
- Local testing with Claude Desktop
{
"mcpServers": {
"mcp-server-kubernetes": {
"command": "node",
"args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
}
}
}
- Local testing with mcp-chat
bun run chat
Contributing
See the CONTRIBUTING.md file for details.
Advanced
For more advanced information such as using SSE transport or Non-destructive mode with ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS
, see the ADVANCED_README.md.
Architecture
Request Flow
The sequence below illustrates how requests flow through the system:
sequenceDiagram
participant Client
participant Transport as StdioTransport
participant Server as MCP Server
participant Handler as Request Handler
participant K8sManager as KubernetesManager
participant K8s as Kubernetes API
Client->>Transport: Send Request via STDIO
Transport->>Server: Forward Request
alt Tools Request
Server->>Handler: Route to tools handler
Handler->>K8sManager: Execute tool operation
K8sManager->>K8s: Make API call
K8s-->>K8sManager: Return result
K8sManager-->>Handler: Process response
Handler-->>Server: Return tool result
else Resource Request
Server->>Handler: Route to resource handler
Handler->>K8sManager: Get resource data
K8sManager->>K8s: Query API
K8s-->>K8sManager: Return data
K8sManager-->>Handler: Format response
Handler-->>Server: Return resource data
end
Server-->>Transport: Send Response
Transport-->>Client: Return Final Response
Publishing New Release
Go to the releases page, click on "Draft New Release", choose a tag in the format v{major}.{minor}.{patch}, add a release title and description/changelog, then publish the release.
This triggers a release build workflow that publishes the release to npm. The version in package.json is automatically updated during this process.
Not Planned
- Authentication / adding clusters to kubectx