☸️ Bridging the Gap: Kubernetes Management with the Model Context Protocol (MCP) ☸️

This repository provides an MCP server that empowers Large Language Models (LLMs) to seamlessly interact with and manage your Kubernetes clusters. By leveraging the Model Context Protocol, this server enables you to build intelligent AI-powered tools for Kubernetes administration, directly integrating cluster insights and control into your LLM applications.

This MCP server acts as a bridge, translating LLM requests into Kubernetes API calls, allowing you to:

Query Cluster State: Retrieve information about pods, services, deployments, nodes, namespaces, and more.
Manage Resources: Create, describe, update, and delete Kubernetes resources directly through natural language commands.
Debug Applications: Fetch logs from pods and monitor Kubernetes events for troubleshooting.
Automate Deployments: Leverage Helm integration to install, upgrade, and manage applications within your cluster.

See it in action!

Integration Examples

Claude Desktop

To integrate this MCP server with Claude Desktop, configure the mcpServers section in your claude_desktop_config.json file:

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

This configuration instructs Claude Desktop to launch the MCP server, enabling it to respond to Kubernetes-related requests. The server automatically connects to your currently configured kubectl context.

Prerequisites:

kubectl installed and in your system's PATH.
A valid kubeconfig file with configured contexts.
Access to a Kubernetes cluster (e.g., minikube, Rancher Desktop, GKE).
(Optional) Helm v3 installed and in your PATH if you plan to use Helm-related features.

Troubleshooting:

If you encounter connection issues, verify your kubectl configuration by running kubectl get pods in a terminal.

mcp-chat

mcp-chat provides a command-line interface for interacting with MCP servers. Use it to test and explore the capabilities of the Kubernetes MCP server:

npx mcp-chat --server "npx mcp-server-kubernetes"

Alternatively, point mcp-chat to your existing Claude Desktop configuration file:

macOS:

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

Key Features

✅ Kubernetes Connectivity: Establishes a secure connection to your Kubernetes cluster.
✅ Resource Discovery: Lists pods, services, deployments, nodes, and namespaces.
✅ Resource Management: Creates, describes, and deletes pods. Supports custom pod and deployment configurations, and allows scaling deployments by updating replicas.
✅ Log Retrieval: Fetches logs from pods, deployments, jobs, and based on label selectors for efficient debugging.
✅ Helm Integration: Supports Helm v3 for installing, upgrading, and uninstalling charts with custom values, namespace specifications, version control, and custom repositories.
✅ kubectl Integration: Leverages kubectl explain and kubectl api-resources for in-depth resource documentation and API discovery.
✅ Event Monitoring: Retrieves Kubernetes events for real-time cluster insights.
✅ Port Forwarding: Establishes port forwarding connections to pods or services.
✅ CronJob Management: Creates, lists, and describes cronjobs.

Local Development Setup

Clone the repository:

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes

Install dependencies:
```
bun install
```

Development Workflow

Start the server in development mode (with file watching):
```
bun run dev
```
Run unit tests:
```
bun run test
```
Build the project:
```
bun run build
```

Local Testing with Inspector:

npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link

Local testing with Claude Desktop:

{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
    }
  }
}

Local testing with mcp-chat:
```
npm run chat
```

Contributing

Please refer to the CONTRIBUTING.md file for guidelines on contributing to this project.

Advanced Configuration

For advanced usage information, including details on using SSE transport, consult the ADVANCED_README.md.

Architecture Overview

The following diagram illustrates the request flow within the MCP Kubernetes server:

sequenceDiagram
    participant Client
    participant Transport as StdioTransport
    participant Server as MCP Server
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Client->>Transport: Send Request via STDIO
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Handler: Route to tools handler
        Handler->>K8sManager: Execute tool operation
        K8sManager->>K8s: Make API call
        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

Publishing a New Release

Navigate to the releases page.
Click "Draft New Release".
Click "Choose a tag" and create a new tag using the "v{major}.{minor}.{patch}" semantic versioning format.
Enter a release title ("Release v{major}.{minor}.{patch}") and a description/changelog.
Click "Publish Release".

This process triggers the cd.yml workflow, which automatically updates the package.json version, builds the release, and publishes it to npm.