adityajoshi12/k8s-mcp-server

Kubernetes MCP Server

This project provides a Model Context Protocol (MCP) server that acts as a bridge to your Kubernetes (K8s) cluster. It leverages the fastmcp framework to expose your K8s API as a set of tools and resources, allowing you to interact with your cluster from any MCP-compatible client, such as Cursor.

Once connected, you can manage your cluster using natural language—listing pods, checking deployment statuses, reading logs, and more, all from within your editor.

Overview

The server works by connecting to your Kubernetes cluster's API server, reading its OpenAPI specification, and dynamically generating MCP tools and resources for the API endpoints. This means that any resource available in your cluster's API, including Custom Resources (CRDs), can be made available to your MCP client.

It uses your local kubeconfig file for authentication, so it works with any Kubernetes cluster that you can access via kubectl.

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.11+
• uv: An extremely fast Python package installer and resolver. The server's run commands are built on it.
• kubectl: The Kubernetes command-line tool.
• A configured ~/.kube/config file pointing to a running Kubernetes cluster.
• Node.js and npx: Required for running the MCP Inspector with the fastmcp dev command.

Installation

1. Clone the repository:

   git clone <your-repository-url>
   cd k8s-mcp-server
   

2. Install dependencies using uv: Assuming you have a pyproject.toml or requirements.txt. If it's a pyproject.toml with an editable install:

   uv pip install -e .
   

Configuration

Kubernetes Configuration

The server will automatically use the current context from your ~/.kube/config file to connect to your Kubernetes cluster.

To switch to a different cluster, simply change your active kubectl context before running the server:

kubectl config use-context <your-cluster-context>

JWT Authentication

This MCP server now includes JWT-based authentication. All API calls require a valid JWT token to be passed in the Authorization header.

Generating JWT Tokens

Use the included token generator to create JWT tokens for testing:

# Generate a token for default user (expires in 1 hour)
python generate_token.py

Using JWT Tokens

When calling the MCP server, clients must include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Token Payload Structure

Generated tokens include the following claims:

• user: Username
• iat: Issued at timestamp
• exp: Expiration timestamp
• permissions: Array of permissions (e.g., ["k8s:read", "k8s:write"])

Running the Server

You can run the server in either development or production mode. Let's assume your main server file is named main.py.

Development Mode

For development, use the fastmcp dev command. This will start the server and the MCP Inspector, which provides a web UI to test and inspect your server's tools and resources.

fastmcp dev main.py

This will launch the Inspector UI, which you can open in your browser to interact with the K8s MCP server.

Production Mode

To run the server for regular use, use the fastmcp run command.

fastmcp run main.py

The server will start and listen for connections from an MCP client.

Installing in an MCP Client (e.g., Cursor)

The fastmcp CLI provides a simple way to install your running server into an MCP client.

Automatic Installation (Recommended)

The easiest way to install the server into Cursor is with the install cursor command. This command generates a special cursor:// deeplink and attempts to open it, which will prompt you to add the server in Cursor.

1. Make sure the MCP server is not running.

2. Run the following command:

   fastmcp install cursor main.py -n "K8s MCP Cluster"
   

   • You can change -n "My K8s Cluster" to any name you prefer.

3. Cursor should open with a dialog to confirm the new MCP server. The server will be started automatically by Cursor using uv in the background.

If Cursor doesn't open automatically, copy the cursor:// link printed in your terminal and paste it into Cursor's command palette (Cmd+K or Ctrl+K) and run it.

Manual Installation

If you use a different MCP client or if automatic installation fails, you can generate the raw JSON configuration.

1. Run the install mcp-config command:

   fastmcp install mcp-config main.py -n "K8s MCP Cluster" --copy
   

2. This copies the configuration JSON to your clipboard.

3. Paste the JSON into your MCP client's custom server configuration section.

Example Usage in an AI Chat

Once the server is installed in your client, you can make requests like:

list all pods in the default namespace

get the logs for the pod my-app-pod-12345

describe the deployment my-nginx-deployment

get the yaml for the service my-service in the production namespace

How It Works

This server is built using the FastMCPOpenAPI class from the fastmcp library. On startup, it performs the following steps:

1. Initializes a Kubernetes API client using your local kubeconfig.
2. Fetches the live OpenAPI v3 specification from your cluster's API server.
3. Parses the OpenAPI spec and intelligently maps API endpoints to MCP components:
   • GET endpoints for single resources (e.g., /api/v1/namespaces/{namespace}/pods/{name}) become ResourceTemplates.
   • GET endpoints for lists of resources (e.g., /api/v1/pods) become Resources.
   • POST, PUT, DELETE, and other action-oriented endpoints become Tools.
4. Exposes all generated components to the connected MCP client, ready for use.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

This README was generated for a server based on the fastmcp framework.