Kubernetes MCP Server

A Model Context Protocol (MCP) server for Kubernetes that provides comprehensive cluster management capabilities without requiring kubectl to be installed locally. This server can be used in both STDIO and HTTP modes, making it perfect for integration with AI assistants like Claude in Cursor/VS Code.

Features

Resource Management

• List Operations: List pods, namespaces, service accounts, deployments, replicasets, secrets, ingresses, services, and custom resource definitions
• Describe Operations: Get detailed information about specific resources
• Action Operations: Delete pods, restart deployments, scale deployments, create resources, and more

Full Tool List

• list_pods - List all pods in a namespace or all namespaces
• list_namespaces - List all namespaces
• list_service_accounts - List service accounts
• list_deployments - List deployments
• list_replicasets - List replica sets
• list_secrets - List secrets (without exposing secret data)
• list_ingresses - List ingresses
• list_services - List services
• list_crds - List custom resource definitions
• describe_pod - Get detailed pod information
• describe_namespace - Get detailed namespace information
• describe_service_account - Get detailed service account information
• describe_deployment - Get detailed deployment information
• describe_replicaset - Get detailed replica set information
• describe_secret - Get secret metadata (without exposing secret data)
• describe_ingress - Get detailed ingress information
• describe_service - Get detailed service information
• delete_pod - Delete a pod
• restart_deployment - Restart a deployment by triggering a rollout
• scale_deployment - Scale a deployment to a specific number of replicas
• create_deployment - Create a new deployment
• create_namespace - Create a new namespace
• get_pod_logs - Get logs from a pod
• get_events - Get cluster events
• port_forward_service - Get instructions for port forwarding to a service
• port_forward_pod - Get instructions for port forwarding to a pod

Prerequisites

• Node.js 18 or higher
• Access to a Kubernetes cluster (local or remote)
• Valid kubeconfig file (typically at ~/.kube/config)

Installation

1. Clone the repository:

git clone <repository-url>
cd kubernetes-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Kubeconfig Setup

The server uses your kubeconfig file to connect to Kubernetes clusters. By default, it looks for the kubeconfig at the standard location (~/.kube/config).

To use a custom kubeconfig location, set the KUBECONFIG environment variable:

export KUBECONFIG=/path/to/your/kubeconfig

Connecting to Different Clusters

The server supports both local and remote Kubernetes clusters:

• Local clusters (minikube, kind, Docker Desktop): Use the default kubeconfig
• Remote clusters (EKS, GKE, AKS, etc.): Configure your kubeconfig with the appropriate cluster credentials

You can switch between contexts using standard kubectl commands:

kubectl config use-context <context-name>

Usage

Running in STDIO Mode (for Cursor/VS Code)

STDIO mode is the default mode for MCP servers integrated with AI assistants.

Development Mode

npm run dev

Production Mode

npm run build
npm start

Running in HTTP Mode

HTTP mode exposes the MCP server over HTTP using Server-Sent Events (SSE).

Development Mode

npm run dev:http

Production Mode

npm run build
npm run start:http

By default, the server runs on port 3000. You can change this by setting the PORT environment variable:

PORT=8080 npm run start:http

Integration with Cursor/VS Code

STDIO Mode (Recommended)

1. Open your Cursor/VS Code settings
2. Navigate to the MCP settings
3. Add this server configuration:

For Cursor: Edit your Cursor settings file (~/.cursor/config/settings.json or through UI):

{
  "mcp": {
    "servers": {
      "kubernetes": {
        "command": "node",
        "args": ["/absolute/path/to/kubernetes-mcp-server/dist/index.js"],
        "env": {
          "KUBECONFIG": "/Users/yourusername/.kube/config"
        }
      }
    }
  }
}

For VS Code with Claude: Edit your MCP settings file:

{
  "mcpServers": {
    "kubernetes": {
      "command": "node",
      "args": ["/absolute/path/to/kubernetes-mcp-server/dist/index.js"],
      "env": {
        "KUBECONFIG": "/Users/yourusername/.kube/config"
      }
    }
  }
}

HTTP Mode

For HTTP mode, configure the MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "kubernetes": {
      "url": "http://localhost:3000/message"
    }
  }
}

Example Usage with AI Assistant

Once integrated, you can ask your AI assistant natural language questions like:

• "List all pods in the default namespace"
• "Show me the deployments in production"
• "Scale the web-app deployment to 3 replicas"
• "Get the logs from the api-server pod in the backend namespace"
• "Create a new namespace called staging"
• "Describe the nginx deployment in kube-system"
• "Restart the frontend deployment"
• "Show me all the events in the cluster"

Development

Project Structure

kubernetes-mcp-server/
├── src/
│   ├── __tests__/          # Test files
│   ├── tools/              # Tool implementations
│   │   ├── list-tools.ts   # List operations
│   │   ├── describe-tools.ts # Describe operations
│   │   └── action-tools.ts # Action operations
│   ├── k8s-client.ts       # Kubernetes client wrapper
│   ├── server.ts           # Main MCP server implementation
│   ├── index.ts            # STDIO entry point
│   └── index-http.ts       # HTTP entry point
├── dist/                   # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Running Tests

npm test

Running Tests in Watch Mode

npm run test:watch

Linting

npm run lint

Security Considerations

1. Kubeconfig Access: The server needs access to your kubeconfig file. Ensure it's properly secured with appropriate file permissions.

2. Secret Handling: The describe_secret and list_secrets tools intentionally do not expose secret data values, only metadata.

3. RBAC: The server operates with the permissions of the kubeconfig context being used. Ensure appropriate RBAC policies are in place in your cluster.

4. HTTP Mode: When using HTTP mode, consider implementing authentication and running the server behind a reverse proxy with TLS in production.

Troubleshooting

"Unable to connect to cluster"

• Verify your kubeconfig is valid: kubectl cluster-info
• Check the KUBECONFIG environment variable is set correctly
• Ensure you have network access to the cluster

"Tool not found" errors

• Rebuild the project: npm run build
• Restart the MCP server
• Check the Cursor/VS Code logs for detailed error messages

Permission Errors

• Verify your kubeconfig user has appropriate RBAC permissions
• Check the service account permissions if using a service account token

Port Forwarding Limitations

Port forwarding operations return instructions rather than maintaining active connections, as MCP tools are designed to be stateless. For active port forwarding, use the returned kubectl command.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: npm test
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with the Model Context Protocol SDK
• Uses the official Kubernetes JavaScript Client

Support

For issues, questions, or contributions, please open an issue on GitHub.