Cluster API

A production-grade Model Context Protocol (MCP) server for the Kubernetes Cluster API (CAPI), enabling AI agents to manage Kubernetes clusters through a secure, standardized interface.

AI Development Disclaimer

⚠️ Important: This repository was primarily created by Claude Code, Anthropic's AI assistant, working in collaboration with a human developer. The code, documentation, tests, and overall architecture were generated through AI-assisted development sessions.

While the code follows industry best practices and includes comprehensive testing, users should:

• Review all code before deploying to production environments
• Understand the security implications of the implementation
• Validate the code meets their specific requirements and compliance standards
• Consider the experimental nature of AI-generated code in critical systems

Overview

The CAPI MCP Server acts as a bridge between AI agents (MCP clients) and CAPI management clusters. It provides a set of tools that abstract the complexity of CAPI into simple, reliable operations for cluster lifecycle management.

Features

V1.0 Scope

• Infrastructure Provider: AWS (via Cluster API Provider for AWS - CAPA)
• Core Tools:
  • list_clusters - List all managed workload clusters
  • get_cluster - Get detailed information for a specific cluster
  • create_cluster - Create a new workload cluster from templates
  • delete_cluster - Delete a workload cluster
  • scale_cluster - Scale worker nodes in a cluster
  • get_cluster_kubeconfig - Retrieve cluster access credentials
  • get_cluster_nodes - List nodes within a cluster
• Security: API key authentication, RBAC, secrets management
• Observability: Structured logging, Prometheus metrics

Architecture

The server follows a modular, extensible design:

• Proxy/Gateway Pattern for bridging MCP and CAPI
• Provider Interface for future multi-cloud support
• Asynchronous handling of long-running CAPI operations
• Security-first approach with least-privilege access

See architecture.md for detailed design documentation.

Development

Prerequisites

• Go 1.24.x
• Docker & Docker Compose
• kubectl
• kind (for local testing)
• golangci-lint

Quick Start

# Clone the repository
git clone https://github.com/capi-mcp/capi-mcp-server.git
cd capi-mcp-server

# Install dependencies
make deps

# Install development tools
make tools

# Run tests
make test

# Build the server
make build

# Run locally (requires API_KEY env var)
API_KEY=your-key make run

Project Structure

/capi-mcp-server
├── /api/v1           # MCP tool/resource schemas
├── /cmd/server       # Application entry point
├── /internal         # Private application code
│   ├── /server       # MCP server engine
│   ├── /service      # Business logic
│   ├── /kube         # CAPI client wrapper
│   └── /config       # Configuration
├── /pkg              # Public libraries
│   ├── /provider     # Provider interface
│   └── /tools        # Tool implementations
├── /deploy           # Deployment artifacts
├── /test             # Test suites
└── /docs             # Documentation

Deployment

The server is deployed as a Kubernetes workload using Helm:

helm install capi-mcp-server ./deploy/charts/capi-mcp-server \
  --set auth.apiKey=$API_KEY \
  --namespace capi-system

Security

• Authentication: API key-based (Bearer token)
• Authorization: Kubernetes RBAC with least-privilege
• Network: Restricted with NetworkPolicies
• Secrets: Never logged, handled securely

Contributing

Please read CLAUDE.md for development guidelines and standards.

Roadmap

See roadmap.md for the project vision and development phases.

License

[License details to be added]