https://github.com/linode/mcp-cluster-api
https://github.com/linode/mcp-cluster-api
Last synced: 20 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/linode/mcp-cluster-api
- Owner: linode
- License: apache-2.0
- Created: 2025-05-27T21:28:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-27T14:59:25.000Z (3 months ago)
- Last Synced: 2026-03-28T00:36:19.835Z (3 months ago)
- Language: Go
- Size: 67.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Authors: AUTHORS
Awesome Lists containing this project
README
# capi-mcp
**capi-mcp** is a tool that integrates [CAPI](https://cluster-api.sigs.k8s.io/) (Cluster API) resources with the [Model Context Protocol (MCP)](https://mcp.so/), enabling programmatic and prompt-based management of Kubernetes clusters and machines.
### What is MCP?
**MCP (Model Context Protocol)** is an open protocol for describing, invoking, and managing tools and prompts in a standardized way. It enables interoperability between tools, agents, and UIs.
### What is CAPI?
**CAPI (Cluster API)** is a Kubernetes project to manage Kubernetes clusters declaratively using Kubernetes-style APIs. It provides a consistent way to create, update, and manage clusters and their infrastructure.
## Prerequisites
- [Go](https://golang.org/doc/install) (v1.20+ recommended)
- [Make](https://www.gnu.org/software/make/)
- [npm](https://nodejs.org/)
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
- Access to a Kubernetes cluster and a valid `kubeconfig.yaml`
## Installation & Build
Clone the repository and build the binary:
```sh
make build
```
## Linting
Run linting (installs golangci-lint if not present):
```sh
make lint
```
## Running & Testing
**Transport support**: `capi-mcp` supports only stdio transport.
To run the MCP inspector with your built binary:
```sh
npx @modelcontextprotocol/inspector -e KUBECONFIG=kubeconfig.yaml bin/capi-mcp
```
Replace `kubeconfig.yaml` with your actual kubeconfig file.
## Usage with Claude and VSCode
### Using with Claude Desktop
To use this MCP server with Claude Desktop, you need to configure it in Claude's settings:
1. **Build the binary** (if not already done):
```sh
make build
```
2. **Locate Claude's configuration file**:
- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- On Linux: `~/.config/Claude/claude_desktop_config.json`
3. **Add the MCP server configuration**:
```json
{
"mcpServers": {
"capi-mcp": {
"command": "/absolute/path/to/capi-mcp/bin/capi-mcp",
"env": {
"KUBECONFIG": "/absolute/path/to/your/kubeconfig.yaml"
}
}
}
}
```
4. **Restart Claude Desktop** to load the new configuration.
5. **Verify the connection**: In a new conversation with Claude, you should see that the CAPI MCP server is connected and running through developer settings.
### Using with VSCode
#### Via Claude Extension
If you're using Claude through a VSCode extension that supports MCP:
1. **Install the Claude extension** from the VSCode marketplace.
2. **Configure the MCP server** in your VSCode settings or the extension's configuration file:
```json
{
"claude.mcpServers": {
"capi-mcp": {
"command": "/absolute/path/to/capi-mcp/bin/capi-mcp",
"env": {
"KUBECONFIG": "/absolute/path/to/your/kubeconfig.yaml"
}
}
}
}
```
3. **Restart VSCode** to apply the configuration.
#### Via VSCode Toolsets
You can also integrate this MCP server with VSCode toolsets for enhanced development workflows:
1. **Create a toolset configuration** in your workspace:
- Open the Command Palette (`Cmd/Ctrl + Shift + P`)
- Run "Toolsets: Configure Toolsets"
- Add a new toolset configuration
2. **Configure the CAPI MCP toolset**:
```json
{
"name": "CAPI MCP Server",
"description": "Cluster API management via MCP",
"tools": [
{
"name": "capi-mcp",
"command": "/absolute/path/to/capi-mcp/bin/capi-mcp",
"env": {
"KUBECONFIG": "/absolute/path/to/your/kubeconfig.yaml"
},
"protocol": "mcp"
}
]
}
```
3. **Use the toolset**:
- Access via the Toolsets panel in the sidebar
- Invoke tools directly from the Command Palette
- Integrate with other VSCode AI features and extensions
This allows you to use CAPI management tools directly within your VSCode development environment alongside other development toolsets.
### Available Tools and Prompts
Once connected, you can use Claude to:
**Tools:**
- `list_clusters` - List all CAPI clusters in your Kubernetes environment
- `get_cluster` - Get detailed information about a specific cluster
- `get_cluster_kubeconfig` - Generate and retrieve a kubeconfig for accessing a CAPI cluster
- `check_upgrade_eligibility` - Verify if a cluster can be safely upgraded to a target Kubernetes version
- `list_machines` - List all machines (nodes) across clusters
- `get_machine` - Get detailed information about a specific machine
- `get_kube_resource` - Get any Kubernetes resource by name, kind, and API version
- `rollout_controlplane` - Rollout a restart of control plane (triggers rolling update - **non-read-only**)
- `get_control_plane_status` - Get status of control plane components for a CAPI cluster
**Prompts:**
- `debug_capi_cluster` - Get step-by-step debugging guidance for cluster issues
- `debug_capi_machine` - Get step-by-step debugging guidance for machine issues
- `restart_control_plane` - Get step-by-step instructions for restarting a cluster's control plane
### Example Usage
Ask Claude / Copilot questions like:
- "Show me all my CAPI clusters"
- "What's the status of my cluster named 'production'?"
- "List all machines in the cluster 'staging'"
- "Get me the kubeconfig for my cluster 'dev-cluster' in namespace 'default'"
- "Check if my cluster can be upgraded to Kubernetes v1.32.0"
- "Help me debug my cluster using the debug_capi_cluster prompt"
- "Get the status of control plane components for my cluster"
- "Get the deployment named 'my-app' in the default namespace using kind 'Deployment' and apiVersion 'apps/v1'"
**Note**: Make sure your `kubeconfig.yaml` file has the necessary permissions to access CAPI resources in your Kubernetes cluster. Some tools like `rollout_controlplane` are write operations and require appropriate RBAC permissions.