MCP CAPI Server

A Model Context Protocol (MCP) server for Cluster API (CAPI), enabling seamless integration between Large Language Models (LLMs) and Kubernetes cluster management through CAPI.

Overview

The MCP CAPI Server provides a bridge between AI assistants (like Claude, GPT, etc.) and Cluster API, allowing natural language interactions for managing Kubernetes clusters across multiple infrastructure providers.

Features

Cluster Management: Create, update, scale, and delete Kubernetes clusters
Multi-Provider Support: Works with AWS, Azure, GCP, vSphere, and more
Machine Operations: Manage control plane and worker nodes
Real-time Monitoring: Watch cluster status changes and events
Resource Discovery: Browse CAPI resources through MCP resources
Guided Workflows: Interactive prompts for complex operations
Multi-Transport Support: Connect via stdio, Server-Sent Events (SSE), or Streamable HTTP
Enhanced CLI: Version management, self-update capability, and comprehensive help system
Backwards Compatible: Maintains compatibility with existing configurations and scripts

Architecture

The MCP CAPI Server is built using:

mcp-go - Go implementation of the Model Context Protocol
client-go - Kubernetes Go client
controller-runtime - Kubernetes controller libraries

Quick Start

Prerequisites

Go 1.24.4 or later
Access to a CAPI management cluster
Kubeconfig configured for the management cluster

Installation

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

# Build the server
make build

# Run the server
make run

Self-Update

The server includes a built-in self-update mechanism:

mcp-capi self-update

Usage

CLI Commands

The MCP server provides several commands:

$ mcp-capi --help
mcp-capi is a Model Context Protocol (MCP) server that provides
tools for interacting with Cluster API (CAPI) clusters. It offers various capabilities
including cluster management, machine operations, scaling, and infrastructure 
provider management.

When run without subcommands, it starts the MCP server (equivalent to 'mcp-capi serve').

Usage:
  mcp-capi [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  self-update Update mcp-capi to the latest version
  serve       Start the MCP CAPI server
  version     Print the version number of mcp-capi

Flags:
  -h, --help      help for mcp-capi
  -v, --version   version for mcp-capi

Use "mcp-capi [command] --help" for more information about a command.

Basic Usage (Backwards Compatible)

Start the MCP server with default settings using stdio transport:

# Both commands are equivalent and start the server
mcp-capi
mcp-capi serve

Multi-Transport Support

The server supports three transport types for different deployment scenarios:

Standard I/O (Default)

Best for MCP client integrations and development:

mcp-capi serve --transport stdio

Server-Sent Events (SSE)

Ideal for web applications and browser-based clients:

mcp-capi serve --transport sse --http-addr :8080

Streamable HTTP

Perfect for HTTP-based integrations and REST-like interactions:

mcp-capi serve --transport streamable-http --http-addr :8080

Advanced Configuration Examples

# Run with SSE transport on custom port with custom endpoints
mcp-capi serve \
  --transport sse \
  --http-addr :9090 \
  --sse-endpoint /events \
  --message-endpoint /messages

# Run with streamable HTTP transport
mcp-capi serve \
  --transport streamable-http \
  --http-addr :8080 \
  --http-endpoint /api/mcp

Version Management

# Check current version
mcp-capi version
mcp-capi --version

# Update to latest version
mcp-capi self-update

Integration with AI Assistants

This MCP server can be integrated with various AI assistants that support the Model Context Protocol:

Cursor: The server can be integrated with Cursor for AI-powered development
VSCode Insiders: Compatible with VSCode Insiders for enhanced coding assistance
Claude Desktop: Add the server to your Claude Desktop configuration
Custom MCP Clients: Use any MCP-compatible client to connect

Example MCP Client Configuration

Standard I/O Transport (Recommended)

{
  "servers": {
    "capi": {
      "command": "/path/to/mcp-capi",
      "env": {
        "KUBECONFIG": "/path/to/kubeconfig"
      }
    }
  }
}

SSE Transport

{
  "servers": {
    "capi": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}

Streamable HTTP Transport

{
  "servers": {
    "capi": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

Available Tools

Cluster Management

capi_create_cluster - Create a new CAPI cluster
capi_list_clusters - List all clusters
capi_get_cluster - Get cluster details
capi_delete_cluster - Delete a cluster
capi_scale_cluster - Scale cluster nodes

Machine Management

capi_list_machines - List machines
capi_get_machine - Get machine details
capi_delete_machine - Delete a specific machine
capi_remediate_machine - Trigger machine health check remediation

MachineDeployment Operations

capi_create_machinedeployment - Create new worker node pool
capi_list_machinedeployments - List machine deployments
capi_scale_machinedeployment - Scale worker nodes
capi_update_machinedeployment - Update MachineDeployment configuration
capi_rollout_machinedeployment - Trigger rolling update

MachineSet Operations

capi_list_machinesets - List machine sets
capi_get_machineset - Get machine set details

Node Operations

capi_drain_node - Safely drain a node
capi_cordon_node - Cordon/uncordon nodes
capi_node_status - Get node status from workload cluster

Infrastructure Provider Tools

Generic

capi_list_infrastructure_providers - List available providers
capi_get_provider_config - Get provider configuration requirements

AWS

capi_aws_list_clusters - List AWS clusters
capi_aws_get_cluster - Get AWS cluster details
capi_aws_create_cluster - Create AWS cluster (placeholder)
capi_aws_update_vpc - Update VPC configuration (placeholder)
capi_aws_manage_security_groups - Manage security groups (placeholder)
capi_aws_get_machine_template - Get/list AWS machine templates

Azure

capi_azure_list_clusters - List Azure clusters
capi_azure_get_cluster - Get Azure cluster details
capi_azure_manage_resource_group - Manage resource groups (placeholder)
capi_azure_network_config - Configure Azure networking (placeholder)

GCP

capi_gcp_list_clusters - List GCP clusters
capi_gcp_get_cluster - Get GCP cluster details
capi_gcp_manage_network - Manage GCP networks (placeholder)

vSphere

capi_vsphere_list_clusters - List vSphere clusters
capi_vsphere_get_cluster - Get vSphere cluster details
capi_vsphere_manage_vms - Manage vSphere VMs (placeholder)

Resources

The server exposes CAPI data through MCP resources:

capi://clusters - List of all clusters
capi://clusters/{name} - Specific cluster details
capi://machines - List of all machines
capi://providers - Available infrastructure providers

Configuration

The server can be configured through environment variables:

KUBECONFIG - Path to kubeconfig file
LOG_LEVEL - Logging level (debug, info, warn, error)

Deployment

Docker

You can run the server in a Docker container:

FROM golang:1.24.4-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o mcp-capi

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/mcp-capi .
EXPOSE 8080
CMD ["./mcp-capi", "serve", "--transport", "sse", "--http-addr", ":8080"]

Systemd Service

Create a systemd service for automatic startup:

[Unit]
Description=MCP CAPI Server
After=network.target

[Service]
Type=simple
User=capi
ExecStart=/usr/local/bin/mcp-capi serve
Environment=KUBECONFIG=/etc/kubernetes/admin.conf
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Development

Project Structure

mcp-capi/
├── cmd/                    # Command implementations
│   ├── root.go            # Root Cobra command
│   ├── serve.go           # Server command with multi-transport support
│   ├── version.go         # Version command
│   ├── selfupdate.go      # Self-update command
│   ├── doc.go             # Package documentation
│   └── *.go               # Tool handlers and server logic
├── pkg/                   # Public packages
│   ├── capi/             # CAPI client and utilities
│   ├── tools/            # MCP tool implementations
│   ├── resources/        # MCP resource handlers
│   └── prompts/          # MCP prompt definitions
├── internal/             # Private packages
├── docs/                 # Documentation
└── examples/             # Usage examples

Building

# Build for current platform
make build

# Build for multiple platforms
make release

# Run tests
make test

# Run with coverage
make test-coverage

Contributing

Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Issues and Support

GitHub Issues: github.com/giantswarm/mcp-capi/issues
Documentation: docs/

Roadmap

See our GitHub Issues for the complete roadmap and planned features.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
cmd		cmd
docs		docs
pkg/capi		pkg/capi
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
renovate.json		renovate.json

License

giantswarm/mcp-capi

Folders and files

Latest commit

History

Repository files navigation

MCP CAPI Server

Overview

Features

Architecture

Quick Start

Prerequisites

Installation

Self-Update

Usage

CLI Commands

Basic Usage (Backwards Compatible)

Multi-Transport Support

Standard I/O (Default)

Server-Sent Events (SSE)

Streamable HTTP

Advanced Configuration Examples

Version Management

Integration with AI Assistants

Example MCP Client Configuration

Standard I/O Transport (Recommended)

SSE Transport

Streamable HTTP Transport

Available Tools

Cluster Management

Machine Management

MachineDeployment Operations

MachineSet Operations

Node Operations

Infrastructure Provider Tools

Generic

AWS

Azure

GCP

vSphere

Resources

Configuration

Deployment

Docker

Systemd Service

Development

Project Structure

Building

Contributing

License

Issues and Support

Roadmap

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages