mcp-kubernetes-server/
├── src/mcp_kubernetes/
│   ├── server.py              # FastMCP server + tool registration
│   ├── config.py              # Pydantic settings (env vars)
│   ├── k8s_client.py          # Kubernetes client manager
│   ├── audit.py               # Structured audit logging
│   ├── utils.py               # Shared utilities
│   ├── auth/
│   │   ├── base.py            # AuthProvider interface
│   │   ├── local.py           # Kubeconfig auth (local engineers)
│   │   ├── aws.py             # AWS EKS IAM auth (pre-signed STS token)
│   │   └── factory.py         # Auto-detect env and create provider
│   ├── tools/
│   │   ├── pods.py            # Pod list/get/logs/exec
│   │   ├── deployments.py     # Deployment list/get/scale/restart/history
│   │   ├── namespaces.py      # Namespace list/create
│   │   ├── services.py        # Service/Ingress list/get
│   │   ├── nodes.py           # Node list/get/pod-list
│   │   ├── configmaps_secrets.py  # ConfigMap/Secret operations
│   │   ├── events.py          # Events/Jobs/CronJobs
│   │   ├── apply.py           # Manifest apply/validate
│   │   └── destructive.py     # Delete operations with guards
│   ├── resources/
│   │   └── cluster.py         # k8s:// URI resources
│   ├── prompts/
│   │   └── diagnose.py        # Guided workflow prompts
│   └── models/
│       └── responses.py       # Pydantic response models
├── tests/                     # Pytest test suite
├── deploy/k8s/                # Kubernetes manifests + IAM policies
├── Dockerfile                 # Multi-stage production image
└── docker-compose.yaml        # Local development

# Uses ~/.kube/config with current-context
MCP_K8S_ENV=local

# Or specify a context
MCP_K8S_ENV=local
MCP_K8S_DEFAULT_CONTEXT=my-team-staging

# Custom kubeconfig path
KUBECONFIG=/path/to/my-kubeconfig

MCP_K8S_ENV=aws
MCP_K8S_EKS_CLUSTER_NAME=my-production-cluster
AWS_DEFAULT_REGION=us-east-1
# AWS credentials come automatically from IRSA (no explicit config needed)

MCP_K8S_ENV=aws
MCP_K8S_EKS_CLUSTER_NAME=my-production-cluster
AWS_DEFAULT_REGION=us-east-1
# Assume a specific IAM role before generating the token:
MCP_K8S_AWS_ROLE_ARN=arn:aws:iam::123456789012:role/ApplicationEngineer
MCP_K8S_AWS_ROLE_SESSION_DURATION=3600

MCP_K8S_CLUSTER_MAP={"prod":"eks-prod-01","staging":"eks-staging-01","dev":"eks-dev-01"}
MCP_K8S_DEFAULT_CLUSTER=staging

# Clone and set up
git clone https://github.com/sthitaprajnas/mcp-kubernetes-server.git
cd mcp-kubernetes-server

# Install with uv
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

# Configure (copy and edit .env)
cp .env.example .env

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "MCP_K8S_ENV": "local",
        "MCP_K8S_ALLOW_DESTRUCTIVE": "true",
        "MCP_K8S_REQUIRE_DESTRUCTIVE_CONFIRMATION": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "MCP_K8S_ENV": "aws",
        "MCP_K8S_EKS_CLUSTER_NAME": "my-cluster",
        "AWS_DEFAULT_REGION": "us-east-1",
        "MCP_K8S_AWS_ROLE_ARN": "arn:aws:iam::123456789012:role/ApplicationEngineer",
        "MCP_K8S_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "mcp-kubernetes",
      "env": {
        "MCP_K8S_ENV": "local"
      }
    }
  }
}

MCP_K8S_TRANSPORT=sse MCP_K8S_PORT=8080 mcp-kubernetes

# Copy and configure
cp .env.example .env
# Edit .env with your settings

# Run with your local kubeconfig
docker-compose up

# MCP server available at http://localhost:8080

docker build -t mcp-kubernetes-server:latest .

docker run -p 8080:8080 \
  -v ~/.kube/config:/home/mcpuser/.kube/config:ro \
  -e MCP_K8S_ALLOW_DESTRUCTIVE=false \
  -e MCP_K8S_TRANSPORT=sse \
  mcp-kubernetes-server:latest

kubectl apply -f deploy/k8s/rbac.yaml

# Get your OIDC provider URL
OIDC=$(aws eks describe-cluster --name my-cluster \
  --query 'cluster.identity.oidc.issuer' --output text | sed 's|https://||')

# Edit the trust policy
sed -i "s/ACCOUNT_ID/$(aws sts get-caller-identity --query Account --output text)/" \
  deploy/k8s/iam-role-trust-policy.json
sed -i "s/REGION/$(aws configure get region)/" \
  deploy/k8s/iam-role-trust-policy.json
sed -i "s|OIDC_PROVIDER_ID|${OIDC}|g" \
  deploy/k8s/iam-role-trust-policy.json

# Create the role
aws iam create-role \
  --role-name mcp-kubernetes-server-role \
  --assume-role-policy-document file://deploy/k8s/iam-role-trust-policy.json

aws iam put-role-policy \
  --role-name mcp-kubernetes-server-role \
  --policy-name eks-access \
  --policy-document file://deploy/k8s/iam-role-inline-policy.json

# Update ACCOUNT_ID in serviceaccount.yaml
sed -i "s/ACCOUNT_ID/$(aws sts get-caller-identity --query Account --output text)/" \
  deploy/k8s/serviceaccount.yaml

kubectl apply -f deploy/k8s/serviceaccount.yaml

# For aws-auth ConfigMap approach:
kubectl edit configmap aws-auth -n kube-system
# Add:
# - rolearn: arn:aws:iam::ACCOUNT_ID:role/mcp-kubernetes-server-role
#   username: mcp-kubernetes-server
#   groups:
#     - mcp-server  # Create a dedicated group with appropriate RBAC

# Update the image registry in deployment.yaml
kubectl apply -f deploy/k8s/deployment.yaml

# Run tests
pytest

# Run tests with coverage
pytest --cov=mcp_kubernetes --cov-report=html

# Lint
ruff check src/ tests/

# Type check
mypy src/