Kubernetes MCP Server
A production-ready Model Context Protocol (MCP) server for managing Kubernetes clusters through Claude and other AI assistants.
Overview
This MCP server provides 20 comprehensive tools for Kubernetes cluster management, enabling AI assistants to perform operations like:
- Managing contexts and clusters
- Listing and inspecting resources (pods, deployments, services, nodes)
- Scaling deployments
- Viewing logs
- Monitoring events
- And much more!
Features
- 20 Kubernetes Tools - Comprehensive coverage of common K8s operations
- Multi-Context Support - Easily switch between multiple clusters
- Dual Output Formats - JSON for parsing, Markdown for readability
- Error Handling - Actionable error messages with suggestions
- Type Safety - Full TypeScript with Zod validation
- Production Ready - RBAC-aware with proper error handling
Quick Start
See QUICKSTART.md for a 5-minute setup guide.
Installation```bash
npm install
npm run build
### Test with MCP Inspector```bash
npm run inspector
Try running: k8s_list_contexts
Integration with Claude Desktop
Edit your claude_desktop_config.json:```json
{
"mcpServers": {
"kubernetes": {
"command": "node",
"args": ["/absolute/path/to/k8s-mcp/dist/index.js"]
}
}
}
Restart Claude Desktop and start managing your Kubernetes clusters!
## Available Tools
### Cluster & Context Management (3 tools)
#### k8s_list_contexts
List all available Kubernetes contexts from kubeconfig.
**Parameters:**
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
List my Kubernetes contexts
k8s_set_context
Switch to a different Kubernetes context.
Parameters:
- contextName (required): Name of the context to switch to
Example:```
Switch to the production context
#### k8s_get_cluster_info
Get information about the current cluster.
**Parameters:**
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
Show me cluster information
Namespace Management (2 tools)
k8s_list_namespaces
List all namespaces in the cluster.
Parameters:
- format (optional): Output format - json or markdown (default: markdown)
Example:```
List all namespaces
#### k8s_create_namespace
Create a new namespace.
**Parameters:**
- `name` (required): Name of the namespace to create
**Example:**```
Create a namespace called staging
Pod Management (4 tools)
k8s_list_pods
List pods in a namespace.
Parameters:
- namespace (optional): Namespace to list from (default: default)
- labelSelector (optional): Filter by labels (e.g., app=nginx)
- fieldSelector (optional): Filter by fields (e.g., status.phase=Running)
- format (optional): Output format - json or markdown (default: markdown)
Examples:```
List all pods in the default namespace
Show me failing pods in production
List pods with label app=nginx
#### k8s_get_pod
Get detailed information about a specific pod.
**Parameters:**
- `name` (required): Name of the pod
- `namespace` (optional): Namespace of the pod (default: `default`)
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
Show me details of pod my-app-12345
k8s_get_pod_logs
Get logs from a pod.
Parameters:
- name (required): Name of the pod
- namespace (optional): Namespace of the pod (default: default)
- container (optional): Container name for multi-container pods
- tailLines (optional): Number of lines to tail
- timestamps (optional): Include timestamps (default: false)
- follow (optional): Stream logs (limited support in MCP)
Examples:```
Get logs from pod my-app-12345
Show me the last 100 lines of logs from pod my-app-12345
#### k8s_delete_pod
Delete a pod from the cluster.
**Parameters:**
- `name` (required): Name of the pod to delete
- `namespace` (optional): Namespace of the pod (default: `default`)
- `gracePeriodSeconds` (optional): Grace period before force deletion
**Example:**```
Delete pod my-app-12345
Deployment Management (5 tools)
k8s_list_deployments
List deployments in a namespace.
Parameters:
- namespace (optional): Namespace to list from (default: default)
- labelSelector (optional): Filter by labels
- format (optional): Output format - json or markdown (default: markdown)
Example:```
List all deployments in production
#### k8s_get_deployment
Get detailed information about a deployment.
**Parameters:**
- `name` (required): Name of the deployment
- `namespace` (optional): Namespace of the deployment (default: `default`)
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
Show me details of deployment my-app
k8s_scale_deployment
Scale a deployment to a specific number of replicas.
Parameters:
- name (required): Name of the deployment
- namespace (optional): Namespace of the deployment (default: default)
- replicas (required): Desired number of replicas
Example:```
Scale my-app deployment to 5 replicas
#### k8s_restart_deployment
Restart a deployment (triggers rolling restart).
**Parameters:**
- `name` (required): Name of the deployment
- `namespace` (optional): Namespace of the deployment (default: `default`)
**Example:**```
Restart the my-app deployment
k8s_rollback_deployment
Rollback a deployment to a previous revision.
Parameters:
- name (required): Name of the deployment
- namespace (optional): Namespace of the deployment (default: default)
- toRevision (optional): Specific revision to rollback to
Example:```
Rollback my-app deployment
### Service Management (2 tools)
#### k8s_list_services
List services in a namespace.
**Parameters:**
- `namespace` (optional): Namespace to list from (default: `default`)
- `labelSelector` (optional): Filter by labels
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
List all services in the default namespace
k8s_get_service
Get detailed information about a service.
Parameters:
- name (required): Name of the service
- namespace (optional): Namespace of the service (default: default)
- format (optional): Output format - json or markdown (default: markdown)
Example:```
Show me details of service my-service
### Node Management (2 tools)
#### k8s_list_nodes
List all nodes in the cluster.
**Parameters:**
- `labelSelector` (optional): Filter by labels
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
List all nodes
Show me nodes that are not ready
k8s_get_node
Get detailed information about a node.
Parameters:
- name (required): Name of the node
- format (optional): Output format - json or markdown (default: markdown)
Example:```
Show me details of node worker-1
### Events & Monitoring (2 tools)
#### k8s_get_events
Get cluster events for debugging.
**Parameters:**
- `namespace` (optional): Namespace to get events from (omit for all)
- `fieldSelector` (optional): Filter by fields
- `limit` (optional): Maximum number of events
- `format` (optional): Output format - `json` or `markdown` (default: `markdown`)
**Example:**```
Show me recent events in the production namespace
Get the last 50 cluster events
k8s_get_resource_status
Get the status of a specific resource.
Parameters:
- resourceType (required): Type - pod, deployment, service, or node
- name (required): Name of the resource
- namespace (optional): Namespace (not for nodes)
- format (optional): Output format - json or markdown (default: markdown)
Example:```
What's the status of deployment my-app?
Check the status of pod my-pod-12345
## Configuration
The server respects standard Kubernetes configuration:
- **KUBECONFIG**: Path to kubeconfig file (default: `~/.kube/config`)
- Supports all contexts defined in your kubeconfig
- Respects RBAC permissions
Optional environment variables (create a `.env` file):```bash
# Default context
K8S_CONTEXT=minikube
# Default namespace
K8S_NAMESPACE=default
# Output format
OUTPUT_FORMAT=markdown
# Log level
LOG_LEVEL=info
Example Conversations with Claude
Once integrated with Claude Desktop, you can have natural conversations:```
You: "What Kubernetes contexts do I have?"
Claude: [Lists all contexts with current one highlighted]
You: "Switch to production and show me all failing pods"
Claude: [Switches context and shows pods with issues]
You: "Get logs from pod xyz"
Claude: [Shows recent logs from the pod]
You: "Scale the api deployment to 10 replicas"
Claude: [Scales the deployment and confirms]
You: "Show me cluster events from the last hour"
Claude: [Displays recent events]
## Architecture```
k8s-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── types.ts # TypeScript types and Zod schemas
│ ├── k8s-client.ts # Kubernetes client wrapper
│ └── tools/
│ ├── formatters.ts # Output formatting utilities
│ ├── context-tools.ts # Context management tools
│ ├── namespace-tools.ts # Namespace tools
│ ├── pod-tools.ts # Pod management tools
│ ├── deployment-tools.ts # Deployment tools
│ ├── service-tools.ts # Service tools
│ ├── node-tools.ts # Node tools
│ └── event-tools.ts # Events and monitoring tools
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
Development
Build```bash
npm run build
### Watch Mode```bash
npm run watch
Testing with Inspector```bash
npm run inspector
```
This opens an interactive interface to test all tools.
Troubleshooting
"Failed to load kubeconfig"
- Ensure
kubectlis installed and configured - Check that
~/.kube/configexists - Verify you can run
kubectl get pods
"Permission denied" errors
- Check your RBAC permissions in the cluster
- Ensure your service account has necessary permissions
- Contact your cluster administrator
"Context not found"
- List available contexts with
k8s_list_contexts - Ensure the context exists in your kubeconfig
- Try
kubectl config get-contextsto verify
"Resource not found"
- Verify the resource name and namespace
- Check you're using the correct context
- Ensure the resource exists with kubectl
Security Considerations
- The server respects RBAC permissions from your kubeconfig
- No credentials are stored by the MCP server
- All authentication uses your existing Kubernetes credentials
- Operations are logged for audit purposes
Requirements
- Node.js >= 18.0.0
- kubectl configured with valid credentials
- Access to a Kubernetes cluster
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
License
MIT
Related Documentation
- QUICKSTART.md - Quick setup guide
- IMPLEMENTATION_SUMMARY.md - Technical implementation details
- PROJECT_OVERVIEW.md - High-level overview
Support
For issues, questions, or contributions, please open an issue on GitHub.
