K8s MCP

A Kubernetes assistant powered by Model Context Protocol (MCP) and Google Gemini.

Requirements

Python 3.10+
Kubernetes cluster with kubeconfig configured
Node.js 18+ (for frontend)
Bun (optional, for faster frontend builds)

Quick Start

Use the Makefile to run different components:

1. MCP Server

Starts the MCP server that communicates with your Kubernetes cluster.

make mcp-server

Requires: Active Kubernetes cluster and configured kubeconfig.

2. CLI Mode

Interactive command-line interface to query your Kubernetes cluster.

make cli

3. Web Application (Backend + Frontend)

Start the backend API server:

make backend

Start the frontend in another terminal:

make frontend

Then open http://localhost:5173 in your browser.

4. All at Once

Start all services in background (development mode):

make dev

Project Structure

k8s_mcp_server.py    - MCP server implementation
mcp_client.py        - CLI client
app/
  backend/           - FastAPI server
  frontend/          - React UI

Configuration

Ensure your kubeconfig is at ~/.kube/config or set the KUBECONFIG environment variable.

The MCP server exposes 32 Kubernetes tools for managing resources, deployments, services, and more.

Features

Real-time Kubernetes operations via MCP tools
Chat interface with tool call results
Inline tool call display in messages
WebSocket streaming for live responses
Automatic WebSocket reconnection

Make Commands

Available make targets (run make <target>):

make help — Show all available commands
make mcp-server — Start the K8s MCP server
make cli — Launch the interactive CLI client
make backend — Start the FastAPI backend
make frontend — Start the React frontend
make dev — Start backend and frontend in the background (development mode)
make logs — Tail service logs
make stop — Stop all background services
make install-deps — Install project dependencies
make clean — Remove build artifacts and cache files

k8s-mcp