Kubernetes Pilot MCP server

The K8s Pilot is a lightweight, centralized control plane server for managing multiple Kubernetes clusters simultaneously. It allows you to observe and control all your clusters from one location using powerful tools and intuitive APIs through the Model Context Protocol (MCP) framework.

Prerequisites

• Python 3.13 or higher
• uv package manager
• Access to Kubernetes clusters (~/.kube/config or in-cluster config)

Installing uv

# For MacOS
brew install uv

# For Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Follow these steps to install and run the K8s Pilot:

# Clone the repository
git clone https://github.com/bourbonkk/k8s-pilot.git
cd k8s-pilot

# Launch with uv + MCP
uv run --with mcp[cli] mcp run k8s_pilot.py

Using with Claude Desktop

To run the K8s Pilot MCP server from within Claude, use this configuration:

{
  "mcpServers": {
    "k8s_pilot": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-cloned-repo>/k8s-pilot",
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "k8s_pilot.py"
      ]
    }
  }
}

Replace <path-to-cloned-repo> with the actual directory where you cloned the repository.

Key Features

Multi-Cluster Management

• Seamlessly interact with multiple Kubernetes clusters
• Perform context-aware operations
• Switch between clusters via MCP prompts

Resource Management

K8s Pilot enables CRUD operations on common Kubernetes resources:

• Deployments, Services, Pods
• ConfigMaps, Secrets, Ingresses
• StatefulSets, DaemonSets
• Roles, ClusterRoles
• PersistentVolumes & Claims

Namespace Operations

• Create and delete namespaces
• List all resources in a namespace
• Manage labels and resource quotas

Node Management

• View node details and conditions
• Cordon/uncordon, label/taint nodes
• List pods per node

Usage Example

You can create a Deployment using the nginx:latest image in the pypy namespace and create a Service that connects to it.

Simply describe what you want to do through the MCP interface, and K8s Pilot will execute the appropriate Kubernetes commands to create these resources.

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 "k8s_pilot" '{"command":"uv","args":["--directory","<path-to-cloned-repo>/k8s-pilot","run","--with","mcp[cli]","mcp","run","k8s_pilot.py"]}'

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": {
        "k8s_pilot": {
            "command": "uv",
            "args": [
                "--directory",
                "<path-to-cloned-repo>/k8s-pilot",
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "k8s_pilot.py"
            ]
        }
    }
}

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": {
        "k8s_pilot": {
            "command": "uv",
            "args": [
                "--directory",
                "<path-to-cloned-repo>/k8s-pilot",
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "k8s_pilot.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect