Kubernetes管理控制协议

# Linux
curl -L https://github.com/achetronic/kubernetes-mcp/releases/latest/download/kubernetes-mcp-linux-amd64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/achetronic/kubernetes-mcp/releases/latest/download/kubernetes-mcp-darwin-amd64.tar.gz | tar xz

# macOS (Apple Silicon)
curl -L https://github.com/achetronic/kubernetes-mcp/releases/latest/download/kubernetes-mcp-darwin-arm64.tar.gz | tar xz

# ~/.config/kubernetes-mcp/config.yaml
server:
  name: "Kubernetes MCP"
  version: "0.1.0"
  transport:
    type: "stdio"

middleware:
  jwt:
    enabled: false

kubernetes:
  default_context: "default"
  contexts:
    - name: "default"
      kubeconfig: "" # Empty: $KUBECONFIG -> ~/.kube/config -> in-cluster
      description: "Local cluster"
  discovery:
    refresh_interval: "10m"

authorization:
  allow_anonymous: true
  policies:
    - name: "allow-all"
      match:
        expression: "true"
      rules:
        - effect: allow
          tools: ["*"]
          contexts: ["*"]
          resources:
            - groups: ["*"]
              resources: ["*"]
            - groups: ["_"]
              resources: ["*"]

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

# config.yaml
server:
  name: "Kubernetes MCP"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

middleware:
  jwt:
    enabled: false

kubernetes:
  default_context: "default"
  contexts:
    - name: "default"
      kubeconfig: "/root/.kube/config"
      description: "My Kubernetes cluster"
  discovery:
    refresh_interval: "10m"

authorization:
  allow_anonymous: true
  policies:
    - name: "allow-all"
      match:
        expression: "true"
      rules:
        - effect: allow
          tools: ["*"]
          contexts: ["*"]
          resources:
            - groups: ["*"]
              resources: ["*"]
            - groups: ["_"]
              resources: ["*"]

docker run -d \
  --name kubernetes-mcp \
  -p 8080:8080 \
  -v ~/.kube/config:/root/.kube/config:ro \
  -v $(pwd)/config.yaml:/config.yaml:ro \
  ghcr.io/achetronic/kubernetes-mcp:latest \
  --config /config.yaml

curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'

# Add the bjw-s repository
helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts
helm repo update

# Download our values file and install
curl -LO https://raw.githubusercontent.com/achetronic/kubernetes-mcp/master/chart/values.yaml
helm install kubernetes-mcp bjw-s/app-template --version 4.2.0 \
  -f values.yaml -n kubernetes-mcp --create-namespace

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kubernetes-mcp
  namespace: kubernetes-mcp
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubernetes-mcp
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
  - nonResourceURLs: ["*"]
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kubernetes-mcp
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubernetes-mcp
subjects:
  - kind: ServiceAccount
    name: kubernetes-mcp
    namespace: kubernetes-mcp

# MCP Server Configuration
server:
  name: "Kubernetes MCP"
  version: "0.1.0"
  transport:
    type: "http" # or "stdio"
    http:
      host: ":8080"

# Middleware Configuration
middleware:
  access_logs:
    excluded_headers:
      - X-Request-Id
    redacted_headers:
      - Authorization

  jwt:
    enabled: true
    validation:
      jwks_uri: "https://keycloak.example.com/realms/mcp/protocol/openid-connect/certs"
      cache_interval: "10s"
      allow_conditions:
        - expression: "has(payload.email)"

  api_keys:
    enabled: true
    keys:
      - name: "ci-cd-pipeline"
        token: "$CI_API_KEY"
        payload:
          sub: "ci-cd-service"
          email: "ci@company.com"
          groups:
            - "ci-cd"

# OAuth Configuration (optional, for remote clients)
oauth_authorization_server:
  enabled: true
  issuer_uri: "https://keycloak.example.com/realms/mcp"

oauth_protected_resource:
  enabled: true
  resource: "https://kubernetes-mcp.example.com/mcp"
  auth_servers:
    - "https://keycloak.example.com/realms/mcp"
  scopes_supported: [openid, profile, email, groups]

# Kubernetes Configuration
kubernetes:
  default_context: "production"
  
  # Explicit contexts with custom names
  contexts:
    - name: "production"
      kubeconfig: "/etc/kubernetes/prod.kubeconfig"
      kubeconfig_context: "gke_myproject_prod"  # Optional: use specific context from kubeconfig
      description: "Production cluster"
      allowed_namespaces: [] # Empty = all allowed
      denied_namespaces:
        - kube-system
        - kube-public
        - istio-system

    - name: "staging"
      kubeconfig: "/etc/kubernetes/staging.kubeconfig"
      description: "Staging cluster"

  # Auto-load kubeconfigs from directory (context name = current-context of each file)
  # contexts_dir: "/etc/kubernetes/clusters/"

  # API discovery cache. The RESTMapper uses it to translate Kind <-> Resource
  # for 'apply_manifest' / 'diff_manifest', to resolve the Kind in
  # 'describe_resource' (used to filter related events) and to surface newly
  # installed CRDs. The cache is invalidated on this interval. Default: 10m.
  discovery:
    refresh_interval: "10m"

  tools:
    bulk_operations:
      # Hard cap on the number of resources delete_resources may match in a
      # single call. Selectors that match more are rejected. Default: 100.
      max_resources_per_operation: 100

# Authorization Configuration
authorization:
  allow_anonymous: false
  policies:
    - name: "sre-full-access"
      description: "SRE team has full access"
      match:
        expression: 'payload.groups.exists(g, g == "sre-team")'
      rules:
        - effect: allow
          tools: ["*"]
          contexts: ["*"]
          resources:
            - groups: ["*"]
              resources: ["*"]
            - groups: ["_"]
              resources: ["*"]

    - name: "developers-limited"
      description: "Developers: full in staging, read-only in prod"
      match:
        expression: 'payload.groups.exists(g, g == "developers")'
      rules:
        - effect: allow
          tools: ["*"]
          contexts: ["staging"]
          resources:
            - groups: ["*"]
              resources: ["*"]
        - effect: deny
          tools: ["delete_resource", "delete_resources", "exec_command"]
          contexts: ["production"]

kubernetes:
  contexts:
    - name: "production"
      kubeconfig: "$PROD_KUBECONFIG"   # Expanded at runtime

middleware:
  jwt:
    enabled: true
    validation:
      jwks_uri: "https://keycloak.example.com/realms/mcp/protocol/openid-connect/certs"
      cache_interval: "10s"
      allow_conditions:
        - expression: 'has(payload.email)'

middleware:
  api_keys:
    enabled: true
    keys:
      - name: "ci-cd-pipeline"
        token: "$CI_API_KEY"
        payload:
          sub: "ci-cd-service"
          email: "ci@company.com"
          groups:
            - "ci-cd"

      - name: "monitoring"
        token: "$MONITORING_API_KEY"
        payload:
          sub: "monitoring-agent"
          groups:
            - "readonly"

- name: "all-except-sensitive"
  match:
    expression: "true"
  rules:
    - effect: allow
      tools: ["*"]
      contexts: ["*"]
      resources:
        - groups: ["*"]
          resources: ["*"]
        - groups: ["_"]
          resources: ["*"]
    - effect: deny
      resources:
        - groups: [""]
          resources: ["secrets"]
        - groups: ["rbac.authorization.k8s.io"]
          resources: ["*"]
        - groups: ["certificates.k8s.io"]
          resources: ["*"]
        - groups: ["*"]
          resources: ["*"]
          namespaces: ["kube-system", "kube-public"]

- name: "no-secrets"
  match:
    expression: "true"
  rules:
    - effect: allow
      tools: ["*"]
      contexts: ["*"]
      resources:
        - groups: ["*"]
          resources: ["*"]
    - effect: deny
      resources:
        - groups: [""]
          resources: ["secrets"]

- name: "read-only-safe"
  match:
    expression: '"developers" in payload.groups'
  rules:
    - effect: allow
      tools: ["get_resource", "list_resources", "describe_resource", "get_logs"]
      contexts: ["*"]
      resources:
        - groups: ["", "apps", "batch", "networking.k8s.io"]
          resources: ["*"]
    - effect: deny
      tools: ["get_*", "list_*", "describe_*"]
      resources:
        - groups: [""]
          resources: ["secrets"]
        - groups: ["rbac.authorization.k8s.io"]
          resources: ["*"]

- name: "write-own-namespaces"
  match:
    expression: '"developers" in payload.groups'
  rules:
    - effect: allow
      tools: ["apply_manifest", "patch_resource", "delete_resource"]
      contexts: ["staging"]
      resources:
        - groups: ["", "apps"]
          resources: ["*"]
          namespaces: ["team-*"]
    - effect: deny
      resources:
        - groups: [""]
          resources: ["secrets"]

- name: "cicd-deploy"
  match:
    expression: 'payload.client_id == "ci-cd-service"'
  rules:
    - effect: allow
      tools: ["apply_manifest", "diff_manifest", "get_resource"]
      contexts: ["production"]
      resources:
        - groups: ["", "apps"]
          resources: ["deployments", "services", "configmaps"]
          namespaces: ["app-*"]

- name: "sre-full-access"
  match:
    expression: '"sre" in payload.groups'
  rules:
    - effect: allow
      tools: ["*"]
      contexts: ["*"]
      resources:
        - groups: ["*"]
          resources: ["*"]
        - groups: ["_"]
          resources: ["*"]

- name: "safe-operations"
  match:
    expression: 'has(payload.sub)'
  rules:
    - effect: allow
      tools: ["get_*", "list_*", "describe_*", "diff_*", "check_*", "scale_*", "*_rollout*", "get_logs"]
      contexts: ["*"]
      resources:
        - groups: ["*"]
          resources: ["*"]
        - groups: ["_"]
          resources: ["*"]
    - effect: allow
      tools: ["delete_resource"]
      resources:
        - groups: [""]
          resources: ["pods"]
          namespaces: ["aplicacion-*", "default"]
    - effect: deny
      tools: ["get_*", "list_*", "describe_*"]
      resources:
        - groups: [""]
          resources: ["secrets", "serviceaccounts"]
        - groups: ["external-secrets.io", "cert-manager.io", "certificates.k8s.io"]
          resources: ["*"]
    - effect: deny
      tools: ["exec_command"]

# Allow discovery and context switching
resources:
  - groups: ["_"]
    resources: ["apidiscovery", "clusterinfo", "contexts"]

"List all pods in the production namespace that are not running"

tool: list_resources
version: v1
resource: pods       # plural lowercase GVR, NOT the Kind
namespace: production
yq_expressions:
  - '.items[] | select(.status.phase != "Running") | {name: .metadata.name, phase: .status.phase}'

# Build binary
make build

# Run with HTTP transport
make run

# Run with custom config
./bin/kubernetes-mcp-linux-amd64 --config /path/to/config.yaml

kubernetes-mcp/
├── cmd/main.go                    # Entrypoint
├── api/config_types.go            # Configuration types
├── internal/
│   ├── k8stools/                  # MCP tools implementation
│   │   ├── manager.go             # Tool registration
│   │   ├── helpers.go             # Shared utilities
│   │   ├── tools_read.go          # get_resource, list_resources, describe_resource
│   │   ├── tools_modify.go        # apply, patch, delete
│   │   ├── tools_scale_rollout.go # scale, rollout operations
│   │   ├── tools_logs_exec.go     # logs, exec, events
│   │   ├── tools_cluster.go       # cluster info, namespaces, api resources
│   │   ├── tools_context.go       # context management
│   │   ├── tools_rbac_metrics.go  # permissions, metrics
│   │   ├── tools_diff.go          # manifest diff
│   │   └── e2e_*_test.go          # End-to-end tests (build tag 'e2e')
│   ├── kubernetes/client.go       # Multi-cluster client manager
│   ├── authorization/evaluator.go # RBAC evaluator
│   ├── yqutil/evaluator.go        # yq expression processor
│   ├── middlewares/               # Auth, JWT, API key, logging middlewares
│   └── handlers/                  # OAuth endpoints
├── docs/
│   ├── config-http.yaml           # HTTP mode example
│   └── config-stdio.yaml          # Stdio mode example
├── chart/                         # Helm values for bjw-s/app-template
├── .agents/                       # Internal architecture & design docs
└── .github/workflows/             # CI: release-binaries, release-docker-images, e2e-tests

func (m *Manager) registerMyTool() {
    tool := mcp.NewTool("my_tool",
        mcp.WithDescription("Does something useful"),
        mcp.WithString("param", mcp.Required(), mcp.Description("A parameter")),
    )
    m.mcpServer.AddTool(tool, m.handleMyTool)
}

func (m *Manager) handleMyTool(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    // ... implementation
    return successResult("Done!"), nil
}

func (m *Manager) RegisterAll() {
    // ... existing tools
    m.registerMyTool()
}

# Format and vet
make fmt
make vet

# Lint (auto-installs golangci-lint)
make lint

# Unit tests (no cluster needed)
make test

# End-to-end tests against a Kind cluster
#   - 'kind-up'       creates a local Kind cluster (idempotent)
#   - 'test-e2e'      runs the e2e suite (build tag 'e2e')
#   - 'kind-down'     deletes the cluster
#   - 'test-e2e-clean' = down + up + tests + down (CI-style)
make test-e2e
make test-e2e-clean

# Run e2e against an existing cluster (no Kind dance)
KMCP_E2E_CONTEXT=$(kubectl config current-context) \
  go test -tags=e2e -timeout 10m ./internal/k8stools/...

make docker-build IMG=your-registry/kubernetes-mcp:tag