k8s MCP 服务

Prerequisites

• Go 1.23 or later
• Access to a Kubernetes cluster
• kubectl configured with appropriate cluster access

Hosted deployment

A hosted deployment is available on Fronteir AI.

Installation

1. Clone the repository:

    git clone https://github.com/reza-gholizade/k8s-mcp-server.git
    cd k8s-mcp-server
    

2. Install dependencies:

    go mod download
    

3. Build the server:

    go build -o k8s-mcp-server main.go
    

Using the Docker Image

You can also run the server using the pre-built Docker image from Docker Hub.

1. Pull the image:

    docker pull ginnux/k8s-mcp-server:latest
    

1. Run the container:

Note: The server supports multiple authentication methods. You can either mount a kubeconfig file (as shown below) or use environment variables for authentication (see Kubernetes Authentication section above).

* SSE Mode (default behavior of the image):

        docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest
        

* Streamable-HTTP Mode:

        docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http
        

* Stdio Mode:

        docker run -i --rm -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode stdio
        

* Custom Port for SSE Mode:

        docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode sse --port 9090
        

* Custom Port for Streamable-HTTP Mode:

        docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http --port 9090
        

* Alternative: Mount entire .kube directory:

        docker run -p 8080:8080 -v ~/.kube:/home/appuser/.kube:ro ginnux/k8s-mcp-server:latest
        

* Using environment variables for authentication (no file mounting required):

        # Using kubeconfig content from environment variable
        docker run -p 8080:8080 \
          -e KUBECONFIG_DATA="$(cat ~/.kube/config)" \
          ginnux/k8s-mcp-server:latest

        # Or using API server URL and token
        docker run -p 8080:8080 \
          -e KUBERNETES_SERVER="https://kubernetes.example.com:6443" \
          -e KUBERNETES_TOKEN="your-token-here" \
          -e KUBERNETES_CA_CERT_PATH="/path/to/ca.crt" \
          -v /path/to/ca.crt:/path/to/ca.crt:ro \
          ginnux/k8s-mcp-server:latest
        

Using with Docker Compose

Create a docker-compose.yml file:

Option 1: Using kubeconfig file (traditional method):

version: '3.8'
services:
  k8s-mcp-server:
    image: ginnux/k8s-mcp-server:latest # Or a specific version
    container_name: k8s-mcp-server
    ports:
      - "8080:8080" # Host:Container, adjust if using a different SERVER_PORT
    volumes:
      - ~/.kube:/home/appuser/.kube:ro # Mount kubeconfig read-only to non-root user home
    environment:
      - KUBECONFIG=/home/appuser/.kube/config
      - SERVER_MODE=sse # Can be 'stdio', 'sse', or 'streamable-http'
      - SERVER_PORT=8080 # Port for SSE/streamable-http modes
    # command: ["--read-only"] # Uncomment this line to enable read-only mode
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Option 2: Using environment variables (no file mounting):

version: '3.8'
services:
  k8s-mcp-server:
    image: ginnux/k8s-mcp-server:latest
    container_name: k8s-mcp-server
    ports:
      - "8080:8080"
    environment:
      - KUBECONFIG_DATA=${KUBECONFIG_DATA} # Set this in your .env file or shell
      # Or use API server and token:
      # - KUBERNETES_SERVER=https://kubernetes.example.com:6443
      # - KUBERNETES_TOKEN=${KUBERNETES_TOKEN}
      - SERVER_MODE=sse
      - SERVER_PORT=8080
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Note: To enable read-only mode, use the command override as shown in Option 1. For stdio mode, you might need to adjust 'ports', add 'stdin_open: true' and 'tty: true', and potentially override the command.

Then start with:

docker compose up -d

Security Considerations

The Docker image runs as a non-root user (appuser with UID 1001) for enhanced security: - The application binary is located at /usr/local/bin/k8s-mcp-server - The kubeconfig should be mounted to /home/appuser/.kube/config - Health checks are enabled to monitor container status - The container includes minimal dependencies (ca-certificates and curl only)

#### Making API Calls (SSE/Streamable-HTTP Mode) Once the server is running in SSE or streamable-http mode, you can make JSON-RPC calls to its HTTP endpoint:

curl -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getAPIResources",
    "arguments": {
      "includeNamespaceScoped": true,
      "includeClusterScoped": true
    }
  }
}' http://localhost:8080/

You can also check the health status:

curl -f http://localhost:8080/

Quick Setup

Automatic Installation (Recommended)

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.sh | bash

Windows (PowerShell):

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.ps1'))

Manual Installation

1. Install the MCP extension in VS Code:

   code --install-extension modelcontextprotocol.mcp
   

1. Add to your VS Code settings.json:

Open VS Code settings (Cmd/Ctrl + ,) → Open Settings JSON → Add:

macOS/Linux:

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

Read-Only Mode (recommended for safety):

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--read-only"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

Kubernetes Tools Only:

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--no-helm"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

Helm Tools Only:

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--no-k8s"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

Read-Only with Kubernetes Tools Only:

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--read-only", "--no-helm"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

Windows:

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server.exe",
         "args": ["--mode", "stdio"],
         "env": {
           "KUBECONFIG": "${env:USERPROFILE}/.kube/config"
         }
       }
     }
   }
   

1. Ensure the binary is in your PATH:

Download the appropriate binary from the releases page and add it to your system PATH.

1. Restart VS Code

Usage

# Add more rules as needed for your use case

apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: k8s-mcp-server-rb subjects: - kind: ServiceAccount name: k8s-mcp-server-sa namespace: default roleRef: kind: ClusterRole name: k8s-mcp-server-role

Using default ~/.kube/config

./k8s-mcp-server

Using custom kubeconfig path

export KUBECONFIG=/path/to/your/kubeconfig ./k8s-mcp-server

**Note:** The server automatically detects which authentication method to use based on the available environment variables and file system. You don't need to explicitly configure the authentication method - it will use the first available method in the priority order listed above.

#### Read-Only Mode

The server supports a read-only mode that disables all write operations, providing a safer way to explore and monitor your Kubernetes cluster without the risk of making changes.

Enable read-only mode with the `--read-only` flag:

You can combine read-only mode with any server mode:

Configuration Options

You can customize the configuration by modifying the settings:

{
  "mcp.mcpServers": {
    "k8s-mcp-server": {
      "command": "k8s-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig",
        "KUBERNETES_CONTEXT": "your-context-name"
      }
    }
  }
}

apiGroup: rbac.authorization.k8s.io

apiVersion: apps/v1 kind: Deployment metadata: name: k8s-mcp-server namespace: default spec: replicas: 1 selector: matchLabels: app: k8s-mcp-server template: metadata: labels: app: k8s-mcp-server spec: serviceAccountName: k8s-mcp-server-sa containers: - name: k8s-mcp-server image: ginnux/k8s-mcp-server:latest ports: - containerPort: 8080 env: - name: SERVER_MODE value: "sse" - name: SERVER_PORT value: "8080"

#### 4. Kubeconfig File Path (Default)

If none of the above methods are available, the server falls back to using a kubeconfig file:

- Uses the path provided via `--kubeconfig` flag (if implemented) or `KUBECONFIG` environment variable
- Defaults to `~/.kube/config` if neither is specified

VS Code Integration

Usage in VS Code

Once configured, you can use the Kubernetes MCP server in VS Code with Claude or other MCP-compatible tools:

1. Open VS Code 2. Access Claude (or other MCP-enabled AI assistant) 3. Use natural language to interact with your Kubernetes cluster: - "List all pods in the default namespace" - "Show me the logs for pod nginx-123" - "Get the CPU usage for worker-node-1" - "Describe the deployment called my-app"

Troubleshooting

• Binary not found: Ensure k8s-mcp-server is in your PATH
• Kubernetes connection issues: Verify your KUBECONFIG path is correct
• Permission errors: Ensure your kubeconfig has the necessary RBAC permissions
• Extension not loading: Restart VS Code after configuration changes