Kubernetes MCP server

The Kubernetes MCP Server is a powerful interface that allows AI tools to interact with your Kubernetes clusters without requiring external dependencies or tools. It provides a native implementation that communicates directly with the Kubernetes API server for optimal performance.

Installation

You can install and use the Kubernetes MCP Server in several ways, depending on your environment.

Using NPX (Node.js users)

If you have npm installed, this is the quickest way to get started:

npx -y kubernetes-mcp-server@latest

For Claude Desktop

Edit your claude_desktop_config.json and add:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ]
    }
  }
}

For VS Code / VS Code Insiders

Install the server in VS Code by running:

# For VS Code
code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'

For Cursor

Edit the mcp.json file:

{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

For Goose CLI

Edit your goose config.yaml and add:

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubernetes-mcp-server@latest

Configuration Options

You can customize the Kubernetes MCP Server using command-line arguments:

npx kubernetes-mcp-server@latest --help

Key configuration options include:

Option	Description
--port	Start server in HTTP/SSE mode on specified port
--log-level	Set logging verbosity (0-9)
--kubeconfig	Path to Kubernetes config file
--read-only	Run in read-only mode (no write operations)
--disable-destructive	Disable destructive operations
--toolsets	Comma-separated list of toolsets to enable

Drop-in Configuration

For advanced setups, the server supports both a main config file and drop-in configuration files:

kubernetes-mcp-server --config /path/to/config.toml --config-dir /path/to/conf.d/

Configuration is loaded in this order:

1. Internal defaults
2. Main configuration file (via --config)
3. Drop-in files (from --config-dir, loaded alphabetically)

You can reload configuration by sending a SIGHUP signal:

pkill -HUP kubernetes-mcp-server

Available Toolsets

The server includes different sets of tools that you can enable or disable:

Toolset	Description	Default
config	Manage kubeconfig	✓
core	Common Kubernetes tools (Pods, Resources, Events)	✓
helm	Manage Helm charts and releases	✓
kiali	Kiali service mesh management tools
kubevirt	KubeVirt virtual machine management

You can specify which toolsets to enable:

npx kubernetes-mcp-server@latest --toolsets "core,config,helm"

This helps reduce context size and improves AI tool selection by only exposing the functionality you need.

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":"npx","args":["-y","kubernetes-mcp-server@latest"]}'

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": "npx",
            "args": [
                "-y",
                "kubernetes-mcp-server@latest"
            ]
        }
    }
}

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": "npx",
            "args": [
                "-y",
                "kubernetes-mcp-server@latest"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect