How vijaykodam/kubernetes-readonly-mcp works
Project Type and Purpose
• This is a backend-only microservice written in Python that implements a Model Context Protocol (MCP) server.
• Its sole purpose is to expose read-only operations against a Kubernetes cluster—no writes, deletes, or updates are allowed.
• Built on FastMCP 2.0 with the official Kubernetes Python client library, it serves as a secure intermediate between AI assistants (or any MCP host) and your cluster.
File Structure Analysis
• Top level:
• pyproject.toml – Python package metadata and dependencies.
• src/kubernetes_readonly_mcp/server.py – entry point defining MCP tools.
• tests/ – unit tests for server logic.
There is no frontend, database, or secondary service—all logic lives in a single Python package.
Key Components
A. MCP Host (e.g., Amazon Q CLI, Claude Desktop, custom AI assistant)
B. uvX (the CLI tool that fetches and runs the published package from PyPI)
C. MCP Server Application
• FastMCP framework layer
• Tool handlers (e.g., list_pods, list_services, get_pod_logs, etc.)
• Kubernetes Python client adapter
D. Kubernetes Cluster
• API server (read‐only access via client)
• Namespaces, Pods, Deployments, Services, Nodes, Events (logical resources)
E. User or AI Assistant
• Sends high‐level prompts/requests to the MCP host
• Receives JSON responses
Relationships and Data Flow
• User/AI Assistant → (MCP protocol request) → MCP Host
• MCP Host → (invokes) → uvX → (loads) → MCP Server code
• MCP Server → (FastMCP routes call) → appropriate tool handler
• Tool handler → (Kubernetes Python client) → Kubernetes API Server
• Kubernetes API Server → (read-only data) → MCP Server → MCP Host → User
Architectural Patterns and Design Principles
• Single-process, single-service microservice.
• Clear separation between:
1. Protocol layer (FastMCP defines RPC bindings)
2. Business logic (tool handlers)
3. Infrastructure adapter (Kubernetes client)
• “Adapter” pattern for wrapping Kubernetes API calls in immutable/read-only tool handlers.
• Dependency injection via FastMCP for pluggable future extensions.
Essential Elements Checklist
[ ] Read-only annotation on all cluster interactions