Kubernetes Server

Enterprise-grade Model Context Protocol (MCP) server for Kubernetes operations built with FastMCP.

Designed for two primary deployment scenarios:

• Local development: Application engineers using their own kubeconfig (with team RBAC roles)
• AWS EKS production: Deployed as a pod with IRSA (IAM Roles for Service Accounts)

Features

Read Operations (always safe)

• List/inspect pods, deployments, services, namespaces, nodes, ingresses
• Stream pod logs with filtering (tail lines, since, previous instance)
• View ConfigMap keys (values optional), Secret metadata (values never exposed)
• List jobs, cronjobs, events (with warning filters)
• Cluster health summary and version info

Write Operations (with dry-run support)

• Scale deployments up/down (with 0-replica warning)
• Rolling restart of deployments
• Create namespaces and configmaps
• Apply YAML/JSON manifests (server-side apply)
• Validate manifests (dry-run only)
• Rollback deployments to previous revisions

Destructive Operations (multi-layer guards)

• Delete pods, deployments, services, configmaps, namespaces
• Rollback deployments
• Every destructive operation requires:
  1. MCP_K8S_ALLOW_DESTRUCTIVE=true (global kill switch)
  2. Protected namespaces (kube-system etc.) are always blocked
  3. Confirmation token: confirm_name must match resource name exactly
  4. Full audit trail

Resources (LLM context)

• k8s://cluster/info — cluster version, identity, node/namespace counts
• k8s://cluster/namespaces — all namespace names
• k8s://cluster/nodes — all nodes with status
• k8s://cluster/health — health summary (not-ready pods, warning events)

Guided Prompts

• diagnose_pod — systematic pod troubleshooting workflow
• diagnose_deployment — deployment health investigation
• pre_deployment_checklist — pre-flight checks before deploying
• cluster_health_report — comprehensive cluster health report
• safe_delete_workflow — guided safe deletion with impact assessment

---

Architecture

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

---

Authentication

Local Mode (Application Engineers)

Uses the standard kubeconfig file. Supports all authentication mechanisms:

• Client certificates
• Bearer tokens
• OIDC / SSO via exec plugins
• AWS EKS via aws eks get-token exec plugin in kubeconfig

# 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

AWS Mode (Deployed in AWS)

Generates EKS authentication tokens via pre-signed AWS STS requests.

When deployed as an EKS pod (IRSA):

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)

When running locally against AWS EKS (assume engineer role):

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

Multi-cluster (AWS):

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

---

Installation

Requirements

• Python 3.11+
• uv (recommended) or pip

Local Development

# 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

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

For AWS EKS:

{
  "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"
      }
    }
  }
}

Claude Code (VS Code Extension)

Add to .claude/mcp.json in your project:

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

SSE Transport (for web-based MCP clients)

MCP_K8S_TRANSPORT=sse MCP_K8S_PORT=8080 mcp-kubernetes

---

Docker Usage

Local development with Docker Compose

# 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

Building the image

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

Running in read-only mode

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

---

Deploying to AWS EKS

1. Create namespace and RBAC

kubectl apply -f deploy/k8s/rbac.yaml

2. Create IAM role for IRSA

# 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

3. Create ServiceAccount with IRSA annotation

# 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

4. Grant the IAM role access in aws-auth (or EKS access entries)

# 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

5. Deploy the server

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

---

Configuration Reference

Variable	Default	Description
MCP_K8S_ENV	auto	Environment mode: local, aws, auto
MCP_K8S_TRANSPORT	stdio	Transport: stdio or sse
MCP_K8S_HOST	0.0.0.0	SSE server bind address
MCP_K8S_PORT	8080	SSE server port
MCP_K8S_LOG_LEVEL	INFO	Log level
MCP_K8S_JSON_LOGS	false	Structured JSON logging
MCP_K8S_AUDIT_LOG_FILE	``	Path to audit log file
KUBECONFIG	~/.kube/config	Kubeconfig path (local mode)
MCP_K8S_DEFAULT_CONTEXT	``	Default kubeconfig context
AWS_DEFAULT_REGION	us-east-1	AWS region
AWS_PROFILE	``	AWS credential profile
MCP_K8S_EKS_CLUSTER_NAME	``	EKS cluster name (AWS mode)
MCP_K8S_AWS_ROLE_ARN	``	IAM role ARN to assume
MCP_K8S_AWS_ROLE_SESSION_DURATION	3600	Assumed role duration (seconds)
MCP_K8S_ALLOW_DESTRUCTIVE	true	Enable delete operations
MCP_K8S_PROTECTED_NAMESPACES	kube-system,kube-public,kube-node-lease	Protected namespaces
MCP_K8S_REQUIRE_DESTRUCTIVE_CONFIRMATION	true	Require name confirmation
MCP_K8S_MAX_BATCH_DELETE	5	Max resources deleteable at once
MCP_K8S_DRY_RUN	false	Global dry-run mode
MCP_K8S_MASK_SECRETS	true	Mask secret values in responses
MCP_K8S_RATE_LIMIT_PER_MINUTE	120	API rate limit
MCP_K8S_REQUEST_TIMEOUT	30	K8s API timeout (seconds)
MCP_K8S_CLUSTER_MAP	{}	JSON map of alias→cluster name
MCP_K8S_DEFAULT_CLUSTER	``	Default cluster alias

---

Security Considerations

Secret Handling

Secret values are never returned by any tool. list_secrets and get_secret_metadata return only key names and metadata. This is hardcoded and cannot be configured away.

Destructive Operations

Three independent gates must all pass:

1. Global flag: MCP_K8S_ALLOW_DESTRUCTIVE=true
2. Namespace protection: namespace not in MCP_K8S_PROTECTED_NAMESPACES
3. Confirmation token: confirm_name must equal the resource name exactly

For namespace deletion, the system namespaces (default, kube-system, kube-public, kube-node-lease) are always blocked regardless of configuration.

Read-Only Mode

Set MCP_K8S_ALLOW_DESTRUCTIVE=false for a completely read-only server suitable for monitoring/observability use cases.

Audit Logging

Every operation (read and write) is audit-logged with:

• ISO 8601 UTC timestamp
• Operation type (READ/WRITE/DELETE/EXEC/SCALE/AUTH)
• Tool name, resource kind/name/namespace
• Identity (IAM ARN or kubeconfig user)
• Cluster name
• Success/failure
• Dry-run flag

Configure MCP_K8S_AUDIT_LOG_FILE=/var/log/mcp-k8s-audit.json for persistent audit logs.

Network Security

When using SSE transport in production:

• Deploy behind an API gateway or reverse proxy with mTLS
• Use Kubernetes NetworkPolicy to restrict pod-to-pod access
• Consider deploying as a sidecar to the Claude client

---

Development

# Run tests
pytest

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

# Lint
ruff check src/ tests/

# Type check
mypy src/

---

Comparison to mcp-server-kubernetes

Inspired by Flux159/mcp-server-kubernetes.

Feature	This Server	Flux159
Language	Python (FastMCP)	TypeScript (Bun)
AWS EKS auth	Native IRSA + role assumption	Via kubeconfig exec plugin
Auto env detection	Yes (IMDS, IRSA, env vars)	No
Destructive guards	3-layer (flag + namespace + confirm)	Non-destructive mode flag
Audit logging	Structured JSON, file+stdout	No
Secret masking	Values never returned	Partial
Multi-cluster	Via cluster_map + switch_cluster	No
Helm support	Planned	Yes
Port forwarding	Planned	Yes

---

License

MIT