Kubernetes MCP Server

A comprehensive Model Context Protocol (MCP) server for secure Kubernetes operations with configurable security modes.

🚀 Features

• 🔒 Security-First: Multiple security modes (Non-destructive, Read-only, Custom, Full access)

• 📦 Modular Architecture: Clean separation of concerns with dedicated modules

• 🐳 Docker Ready: Production-ready containerized deployment

• ⚡ FastMCP Integration: Built on FastMCP 2.11.3 framework

• 🎯 Comprehensive Coverage: Support for all major Kubernetes and Istio resources

• 💾 Backup Operations: Safe backup-before-delete functionality

• 🔧 Helm Support: Complete Helm chart lifecycle management

📋 Prerequisites

• Python 3.12+

• Docker (for containerized deployment)

• Kubernetes cluster access

• kubectl configured

• Helm 3.x (optional, for Helm operations)

🛠️ Installation

Option 1: Docker Deployment (Recommended)

# Build the Docker image
docker build -t kubectl-mcp-server:latest .

# Run with non-destructive security mode
docker run -d \
  --name kubectl-mcp-server \
  -p 8000:8000 \
  -v ~/.kube:/root/.kube:ro \
  -e KUBECONFIG=/root/.kube/config \
  -e ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true \
  kubectl-mcp-server:latest

Option 2: Local Development

# Install dependencies
pip install -r requirements.txt

# Run the server
python run_server.py --transport stdio

🔐 Security Modes

1. Non-Destructive Mode (Recommended for Production)

export ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true

• ✅ Allows: All read operations, create, scale, backup

• ❌ Blocks: Delete operations, Helm uninstalls

2. Read-Only Mode (Monitoring/Observability)

export ALLOW_ONLY_READONLY_TOOLS=true

• ✅ Allows: Get/list operations, logs, health checks

• ❌ Blocks: All write operations

3. Custom Mode (Granular Control)

export ALLOWED_TOOLS="get_pods,get_deployments,get_services"

• ✅ Allows: Only specified tools

• ❌ Blocks: Everything else

4. Full Access Mode (Development Only)

# No environment variables set

• ✅ Allows: All operations

• ⚠️ Warning: Use only in development environments

🎯 Supported Resources

Core Kubernetes Resources

• Workloads: Pods, Deployments, ReplicaSets, StatefulSets, DaemonSets

• Services: Services, Endpoints, Ingresses

• Configuration: ConfigMaps, Secrets

• Storage: PersistentVolumes, PersistentVolumeClaims, StorageClasses

• RBAC: Roles, ClusterRoles, RoleBindings, ClusterRoleBindings, ServiceAccounts

• Networking: NetworkPolicies

• Cluster: Namespaces, Nodes, Events

Istio Service Mesh

• Traffic Management: VirtualServices, DestinationRules, Gateways

• Security: ServiceEntries

Helm Operations

• Chart Management: Install, upgrade, uninstall

• Release Operations: List, status, values

• Repository Management: Add, list repositories

🔧 Configuration

Environment Variables

Windsurf Integration

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "kubectl-safe": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/yourusername/.kube:/root/.kube:ro",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-e", "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true",
        "-e", "TRANSPORT=stdio",
        "kubectl-mcp-server:latest",
        "python", "run_server.py", "--transport", "stdio"
      ]
    }
  }
}

📚 Usage Examples

Basic Operations

# List all pods
python run_server.py --transport stdio
# Then use MCP client to call: get_pods_tool

# Get deployments in specific namespace
# MCP call: get_deployments_tool(namespace="production")

# Scale a deployment
# MCP call: scale_deployment_tool(name="myapp", replicas=3, namespace="default")

Backup Operations

# Backup a resource before deletion
# MCP call: backup_resource_tool(name="myapp", resource_type="deployment", namespace="default")

# Safe delete (backup + delete)
# MCP call: backup_and_delete_resource_tool(name="myapp", resource_type="deployment")

Helm Operations

# Install a Helm chart
# MCP call: install_helm_chart_tool(name="myapp", chart="nginx", namespace="default")

# List Helm releases
# MCP call: list_helm_releases_tool(namespace="default")

🏗️ Architecture

kubectl-mcp-server/
├── run_server.py                 # Main entry point
├── kubectl_mcp_tool/
│   ├── mcp_server.py            # MCP server implementation
│   └── tools/                   # Modular tool implementations
│       ├── kubectl_get.py       # Read operations
│       ├── kubectl_operations.py # Utility operations
│       ├── kubectl_delete.py    # Destructive operations
│       ├── kubectl_backup.py    # Backup operations
│       └── helm_operations.py   # Helm chart operations
├── Dockerfile                   # Container configuration
└── requirements.txt            # Python dependencies

🔒 Security Best Practices

1. Use Non-Destructive Mode in production environments

2. Mount kubeconfig read-only in containers

3. Regularly backup critical resources

4. Monitor logs for security events

5. Use least-privilege RBAC policies

6. Validate configurations before deployment

🐛 Troubleshooting

Common Issues

Authentication Errors

# Check kubeconfig
kubectl config current-context

# Verify cluster access
kubectl get nodes

Container Issues

# Check container logs
docker logs kubectl-mcp-server

# Verify volume mounts
docker exec -it kubectl-mcp-server ls -la /root/.kube/

MCP Connection Issues

# Test server directly
python run_server.py --transport stdio --debug

# Validate JSON configuration
cat ~/.codeium/windsurf/mcp_config.json | python3 -m json.tool

📊 Monitoring

Health Checks

• Server startup logs indicate security mode

• Failed operations are logged with details

• Resource access attempts are audited

Metrics

• Operation success/failure rates

• Security mode violations

• Resource access patterns

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure security modes work correctly

5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues and questions:

1. Check the troubleshooting section

2. Review container logs

3. Validate Kubernetes connectivity

4. Verify MCP configuration

🔄 Version History

• v1.0.0: Initial release with security modes and comprehensive Kubernetes support

• FastMCP 2.11.3 integration

• Docker containerization

• Windsurf integration