k8s-ai

Kubernetes AI Management System (K8s AI) provides an MCP server that combines AI-driven diagnostics and Kubernetes tooling to help you observe, analyze, and manage your cluster. The MCP server is backed by an agent and a suite of tools for cluster health checks, resource usage analysis, log examination, and various Kubernetes surface inspections such as pods, services, ingresses, storage, and Helm releases. You can interact with the system in natural language queries, and the AI engine translates those queries into actionable commands against your cluster, returning concise summaries and actionable recommendations. To get started, run the MCP server (via Java/Maven build or Docker image) and connect your MCP host (e.g., Claude Desktop) to leverage the integrated tooling for real-time diagnostics and guided operations.

Prerequisites:

• Java 17 or later
• Maven 3.8 or later
• A configured Kubernetes cluster with kubeconfig at ~/.kube/config
• Docker installed if you plan to run via Docker

Option A: Build and run locally (Java)

1. Clone the repository and navigate to the project root
2. Build all modules: mvn clean package
3. Run the MCP server from the built artifact: java -jar mcp-server/target/mcp-server-1.0-SNAPSHOT.jar

Option B: Run via Docker (recommended for isolation)

1. Ensure Docker is running and pull/build the image for the MCP server (image name example: k8s-ai-mcp-server:latest).
2. Run the container: docker run -it --rm -v ~/.kube/config:/root/.kube/config k8s-ai-mcp-server:latest
3. Verify the server starts and is reachable through the configured MCP host interface.

Prerequisites recap:

• JDK 17+ and Maven 3.8+ (for local build)
• Kubernetes cluster access via kubeconfig (~/.kube/config)
• Docker if using containerized deployment

Notes and tips:

• The project exposes an MCP server (mcp-server) and an agent module; you can run either depending on your workflow. The agent offers a REST API for cluster analysis, while the MCP server provides an integrated toolset for querying Kubernetes state.
• For best results, ensure your kubeconfig is properly configured and that your cluster is reachable from the machine running the MCP server.
• If you run via Docker, consider mounting your kubeconfig into the container to enable cluster access (example: -v ~/.kube/config:/root/.kube/config).
• When using Claude Desktop or any MCP host, refer to the mcp-server documentation for integration steps and how to connect your host to the MCP server.
• The system supports a wide range of capabilities: cluster health/diagnostics, network analysis, storage management, Job/CronJob analysis, and Helm release management.
• If you encounter Java memory issues, consider adjusting JVM options or running with a container that provides sufficient memory headroom.