Kubernetes MCP Server 🚀
The Kubernetes MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Kubernetes APIs, enabling advanced automation and interaction capabilities for developers, operators, and AI tools.
Table of Contents
- Kubernetes MCP Server 🚀
- Table of Contents
- Overview 📊
- Prerequisites ✅
- Installation 💻
- Usage with Claude Desktop
- Usage with VS Code
- Usage with Cline
- Build from source
- Command Line Options ⌨️
- Server Transport Options 🔄
- stdio
- SSE
- Access Control 🔒
- Tools 🧰
- Resource Operations 📦
- Management Operations ⚙️
- Future Enhancements 🔮
- Contributing 👥
- License ⚖️
Overview 📊
This MCP server enables AI tools to interact with Kubernetes clusters using natural language, providing capabilities to:
- 🔍 Retrieve and analyze cluster resources
- 📈 Monitor deployments, pods, and services
- 🛠️ Execute common kubectl operations through AI interfaces
- 🔧 Troubleshoot cluster issues with AI assistance
Prerequisites ✅
- A Kubernetes cluster with API access
- Valid kubeconfig file or service account credentials
- Appropriate RBAC permissions for desired operations
Installation 💻
Usage with Claude Desktop
Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):```json
{
"mcpServers": {
"kubernetes": {
"command": "path/to/k8smcp",
"args": [
"stdio",
"--kubeconfig=/path/to/your/kubeconfig"
]
}
}
}
### Usage with VS Code
Add the following to your VS Code User Settings (JSON) file or `.vscode/mcp.json` in your workspace:```json
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "kubeconfig_path",
"description": "Path to kubeconfig file",
"default": "${env:HOME}/.kube/config"
}
],
"servers": {
"kubernetes": {
"command": "path/to/k8smcp",
"args": [
"stdio",
"--kubeconfig=/path/to/your/kubeconfig"
]
}
}
}
}
Usage with Cline
Add the following to your Cline configuration file (path/to/cline_mcp_settings.json after selecting "Configure MCP Servers"):```json
{
"mcpServers": {
"kubernetes": {
"disabled": false,
"timeout": 60,
"command": "path/to/k8smcp",
"args": [
"stdio",
"--read-only=false"
"--kubeconfig=/path/to/your/kubeconfig"
],
"env": {
"K8S_MCP_TOOLSETS": "all"
},
"transportType": "stdio"
}
}
}
Make sure to update the `command` value with the path to your k8smcp executable. You can set the server configurations either using `args` or `env`.
### Build from source
Clone the repository and build the binary:```bash
git clone https://github.com/briankscheong/k8s-mcp-server.git
cd k8s-mcp-server
make build
Or install directly with Go:```bash
go install github.com/briankscheong/k8s-mcp-server/cmd/k8s-mcp-server@latest
## Command Line Options ⌨️```txt
A Kubernetes MCP Server that provides tools for interacting with Kubernetes clusters.
Environment Variables:
K8S_MCP_KUBECONFIG Path to kubeconfig file
K8S_MCP_NAMESPACE Default Kubernetes namespace
K8S_MCP_IN_CLUSTER Use in-cluster config (true/false)
K8S_MCP_READ_ONLY Restrict to read-only operations (true/false)
K8S_MCP_RESOURCE_TYPES Comma-separated list of resource types
K8S_MCP_TOOLSETS Comma-separated list of toolsets to enable
K8S_MCP_EXPORT_TRANSLATIONS Export translations (true/false)
Usage:
k8smcp [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
sse Start sse server
stdio Start stdio server
Flags:
--export-translations Save translations to a JSON file
-h, --help help for k8smcp
--in-cluster Use in-cluster config instead of kubeconfig file
--kubeconfig string Path to the kubeconfig file (default "/Users/briancheong/.kube/config")
--namespace string Default Kubernetes namespace to target (default "default")
--read-only Restrict operations to read-only (no create, update, delete) (default true)
--resource-types strings Comma separated list of Kubernetes resource types to enable (pods,deployments,services,configmaps,namespaces,nodes) (default [all])
--toolsets strings Comma separated list of tools to enable (default [all])
-v, --version version for k8smcp
Use "k8smcp [command] --help" for more information about a command.
Server Transport Options 🔄
stdio
The stdio transport is the default and recommended option for most users for local integration:```bash
k8smcp stdio --kubeconfig=/path/to/your/kubeconfig
### SSE
The `sse` transport provides support for HTTP-based JSON-RPC message transport. This can be helpful when deploying the server in a Kubernetes cluster that needs to expose a port for client connection.```bash
k8smcp sse --in-cluster=true
> [!NOTE]
> The --in-cluster=true flag needs to be set if the server is deployed in a Kubernetes cluster.
Access Control 🔒
By default, the server applies the permissions of the provided kubeconfig or service account. For enhanced security, you can:
- Create a dedicated service account with restricted RBAC permissions
- Set namespace limits to prevent cross-namespace operations
- Enable read-only mode to prevent mutations to cluster state
Tools 🧰
The Kubernetes MCP Server provides a comprehensive set of tools for interacting with your Kubernetes cluster.
Resource Operations 📦
- get_pod - Get detailed information about a specific pod
namespace: Pod namespace (string, optional, defaults to current namespace)-
name: Pod name (string, required) -
list_pods - List pods in a namespace
namespace: Namespace to list pods from (string, optional, defaults to current namespace)label_selector: Filter pods by label selector (string, optional)-
field_selector: Filter pods by field selector (string, optional) -
get_pod_logs - Get logs from a pod
namespace: Pod namespace (string, optional, defaults to current namespace)name: Pod name (string, required)container: Container name (string, optional, defaults to first container)tail_lines: Number of lines to retrieve from the end (number, optional)-
previous: Get logs from previous container instance (boolean, optional) -
get_deployment - Get information about a specific deployment
namespace: Deployment namespace (string, optional, defaults to current namespace)-
name: Deployment name (string, required) -
list_deployments - List deployments in a namespace
namespace: Namespace to list deployments from (string, optional, defaults to current namespace)-
label_selector: Filter deployments by label selector (string, optional) -
get_service - Get information about a specific service
namespace: Service namespace (string, optional, defaults to current namespace)-
name: Service name (string, required) -
list_services - List services in a namespace
namespace: Namespace to list services from (string, optional, defaults to current namespace)-
label_selector: Filter services by label selector (string, optional) -
get_configmap - Get information about a specific ConfigMap
namespace: ConfigMap namespace (string, optional, defaults to current namespace)-
name: ConfigMap name (string, required) -
list_configmaps - List ConfigMaps in a namespace
namespace: Namespace to list ConfigMaps from (string, optional, defaults to current namespace)-
label_selector: Filter ConfigMaps by label selector (string, optional) -
list_namespaces - List all namespaces in the cluster
-
No parameters required
-
list_nodes - List all nodes in the cluster
- No parameters required
Management Operations ⚙️
- delete_pod - Delete a pod from a namespace
namespace: Pod namespace (string, optional, defaults to current namespace)name: Pod name (string, required)-
grace_period_seconds: Grace period before deletion (number, optional) -
scale_deployment - Scale a deployment to a specific number of replicas
namespace: Deployment namespace (string, optional, defaults to current namespace)name: Deployment name (string, required)replicas: Number of replicas (number, required)
> [!IMPORTANT]
> By default, tools that involve modification of resources in the cluster are disabled. To enable them, you have to set the --read-only=false flag or the K8S_MCP_READ_ONLY=false environment variable.
Future Enhancements 🔮
- Enhanced RBAC integration for fine-grained access control
- Support for more kubernetes resources
- Support for custom resource definitions (CRDs)
- Helm chart management capabilities for deployment
- Cluster monitoring and alerting integration
- Support for multiple concurrent cluster connections
Contributing 👥
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License ⚖️
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ for the Kubernetes and AI communities.
