Kubernetes MCP server

The Kubernetes MCP Server provides seamless integration with Kubernetes APIs through the Model Context Protocol (MCP), enabling AI tools to interact with Kubernetes clusters using natural language. This server allows you to retrieve and analyze cluster resources, monitor deployments, execute kubectl operations, and troubleshoot issues using AI assistance.

Prerequisites

Before installing the Kubernetes MCP Server, ensure you have:

• A Kubernetes cluster with API access
• Valid kubeconfig file or service account credentials
• Appropriate RBAC permissions for desired operations

Installation

Build from Source

To build the binary from source:

git clone https://github.com/briankscheong/k8s-mcp-server.git
cd k8s-mcp-server
make build

Configuring with AI Tools

Claude Desktop

Add the following to your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "kubernetes": {
      "command": "path/to/k8smcp",
      "args": [
        "stdio",
        "--kubeconfig=/path/to/your/kubeconfig"
      ]
    }
  }
}

VS Code

Add the following to your VS Code User Settings (JSON) file or .vscode/mcp.json in your workspace:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "kubeconfig_path",
        "description": "Path to kubeconfig file",
        "default": "${env:HOME}/.kube/config"
      }
    ],
    "servers": {
      "kubernetes": {
        "command": "path/to/k8smcp",
        "args": [
          "stdio",
          "--kubeconfig=/path/to/your/kubeconfig"
        ]
      }
    }
  }
}

Cline

Add the following to your Cline configuration file (located at path/to/cline_mcp_settings.json after selecting "Configure MCP Servers"):

{
  "mcpServers": {
    "kubernetes": {
      "disabled": false,
      "timeout": 60,
      "command": "path/to/k8smcp",
      "args": [
        "stdio",
        "--read-only=false"
        "--kubeconfig=/path/to/your/kubeconfig"
      ],
      "env": {
        "K8S_MCP_TOOLSETS": "all"
      },
      "transportType": "stdio"
    }
  }
}

Command Line Options

The server supports various command line options to customize behavior:

Environment Variables:
  K8S_MCP_KUBECONFIG            Path to kubeconfig file
  K8S_MCP_NAMESPACE             Default Kubernetes namespace
  K8S_MCP_IN_CLUSTER            Use in-cluster config (true/false)
  K8S_MCP_READ_ONLY             Restrict to read-only operations (true/false)
  K8S_MCP_RESOURCE_TYPES        Comma-separated list of resource types
  K8S_MCP_TOOLSETS              Comma-separated list of toolsets to enable
  K8S_MCP_EXPORT_TRANSLATIONS   Export translations (true/false)

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  sse         Start sse server
  stdio       Start stdio server

Flags:
      --export-translations      Save translations to a JSON file
  -h, --help                     help for k8smcp
      --in-cluster               Use in-cluster config instead of kubeconfig file
      --kubeconfig string        Path to the kubeconfig file (default "/Users/briancheong/.kube/config")
      --namespace string         Default Kubernetes namespace to target (default "default")
      --read-only                Restrict operations to read-only (no create, update, delete) (default true)
      --resource-types strings   Comma separated list of Kubernetes resource types to enable (default [all])
      --toolsets strings         Comma separated list of tools to enable (default [all])
  -v, --version                  version for k8smcp

Server Transport Options

stdio

The stdio transport is recommended for most users for local integration:

k8smcp stdio --kubeconfig=/path/to/your/kubeconfig

SSE

The sse transport provides HTTP-based JSON-RPC message transport, useful when deploying the server in a Kubernetes cluster:

k8smcp sse --in-cluster=true

Access Control

By default, the server applies the permissions of the provided kubeconfig or service account. For enhanced security:

• Create a dedicated service account with restricted RBAC permissions
• Set namespace limits to prevent cross-namespace operations
• Enable read-only mode to prevent mutations to cluster state

Available Tools

Resource Operations

• get_pod - Get detailed information about a specific pod

  • namespace: Pod namespace (string, optional, defaults to current namespace)
  • name: Pod name (string, required)

• list_pods - List pods in a namespace

  • namespace: Namespace to list pods from (string, optional, defaults to current namespace)
  • label_selector: Filter pods by label selector (string, optional)
  • field_selector: Filter pods by field selector (string, optional)

• get_pod_logs - Get logs from a pod

  • namespace: Pod namespace (string, optional, defaults to current namespace)
  • name: Pod name (string, required)
  • container: Container name (string, optional, defaults to first container)
  • tail_lines: Number of lines to retrieve from the end (number, optional)
  • previous: Get logs from previous container instance (boolean, optional)

• get_deployment - Get information about a specific deployment

  • namespace: Deployment namespace (string, optional, defaults to current namespace)
  • name: Deployment name (string, required)

• list_deployments - List deployments in a namespace

  • namespace: Namespace to list deployments from (string, optional, defaults to current namespace)
  • label_selector: Filter deployments by label selector (string, optional)

• get_service - Get information about a specific service

  • namespace: Service namespace (string, optional, defaults to current namespace)
  • name: Service name (string, required)

• list_services - List services in a namespace

  • namespace: Namespace to list services from (string, optional, defaults to current namespace)
  • label_selector: Filter services by label selector (string, optional)

• get_configmap - Get information about a specific ConfigMap

  • namespace: ConfigMap namespace (string, optional, defaults to current namespace)
  • name: ConfigMap name (string, required)

• list_configmaps - List ConfigMaps in a namespace

  • namespace: Namespace to list ConfigMaps from (string, optional, defaults to current namespace)
  • label_selector: Filter ConfigMaps by label selector (string, optional)

• list_namespaces - List all namespaces in the cluster

  • No parameters required

• list_nodes - List all nodes in the cluster

  • No parameters required

Management Operations

• delete_pod - Delete a pod from a namespace

  • namespace: Pod namespace (string, optional, defaults to current namespace)
  • name: Pod name (string, required)
  • grace_period_seconds: Grace period before deletion (number, optional)

• scale_deployment - Scale a deployment to a specific number of replicas

  • namespace: Deployment namespace (string, optional, defaults to current namespace)
  • name: Deployment name (string, required)
  • replicas: Number of replicas (number, required)

Important: By default, tools that modify cluster resources are disabled. To enable them, set the --read-only=false flag or the K8S_MCP_READ_ONLY=false environment variable.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "kubernetes" '{"command":"path/to/k8smcp","args":["stdio","--kubeconfig=/path/to/your/kubeconfig"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "kubernetes": {
            "command": "path/to/k8smcp",
            "args": [
                "stdio",
                "--kubeconfig=/path/to/your/kubeconfig"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "kubernetes": {
            "command": "path/to/k8smcp",
            "args": [
                "stdio",
                "--kubeconfig=/path/to/your/kubeconfig"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect