pi-controller-mcp

MCP (Model Context Protocol) server for managing Raspberry Pi K3s clusters via AI assistants like Claude Code.

Features

🎯 26 AI Tools for complete cluster lifecycle management
📊 7 Resources providing real-time cluster context
🔐 Secure Authentication with JWT and API keys
🛡️ RBAC Integration respecting viewer/operator/admin roles
🔌 GPIO Control for hardware management
📦 Zero Configuration works out of the box with npx

Quick Start

1. Configure Claude Code

Add to your ~/.config/claude-code/mcp.json (or project .mcp.json):

{
  "mcpServers": {
    "pi-controller": {
      "command": "npx",
      "args": ["-y", "pi-controller-mcp"],
      "env": {
        "PI_CONTROLLER_URL": "https://pi-controller.local:8080",
        "PI_CONTROLLER_USERNAME": "admin",
        "PI_CONTROLLER_PASSWORD": "your-password"
      }
    }
  }
}

2. Start Using with AI

User: "Create a 3-node K3s cluster called 'homelab'"

Claude: I'll help you create a cluster...
[Uses create_cluster tool]
[Uses discover_nodes tool]
[Uses provision_cluster tool]

Available Tools

Cluster Management

create_cluster - Create cluster definition
list_clusters - List all clusters
get_cluster_status - Get detailed cluster status
provision_cluster - Provision K3s on nodes
scale_cluster - Scale cluster nodes
delete_cluster - Delete cluster

Node Management

discover_nodes - List discovered Raspberry Pi nodes
get_node_info - Get node details and hardware info
register_node - Manually register a node
provision_node - Provision K3s on single node
deprovision_node - Remove K3s from node

GPIO Control

list_gpio_devices - List all GPIO devices
create_gpio_device - Register GPIO device
read_gpio_pin - Read pin value
write_gpio_pin - Write to pin (HIGH/LOW)
reserve_gpio_pin - Reserve pin for exclusive use
release_gpio_pin - Release reservation
get_gpio_readings - Get historical readings
delete_gpio_device - Remove GPIO device

Deployment

deploy_pod - Deploy Kubernetes pod
get_pod - Get pod information
delete_pod - Delete pod

Certificate Authority

initialize_ca - Initialize CA
issue_certificate - Issue new certificate
list_certificates - List all certificates
revoke_certificate - Revoke certificate

Available Resources

Resources provide AI with real-time context about your clusters:

cluster://{cluster_id}/status - Cluster health and metrics
cluster://{cluster_id}/nodes - Node list with status
node://{node_id}/info - Hardware specs and capabilities
node://{node_id}/metrics - CPU, memory, temperature
node://{node_id}/gpio - GPIO devices on node
gpio://{gpio_id}/state - Current pin state
system://health - Overall system health

Configuration

Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | PI_CONTROLLER_URL | ✅ | Pi-controller API URL | - | | PI_CONTROLLER_API_KEY | ⚠️ | API key for auth | - | | PI_CONTROLLER_USERNAME | ⚠️ | Username for auth | - | | PI_CONTROLLER_PASSWORD | ⚠️* | Password for auth | - | | PI_CONTROLLER_TLS_VERIFY | ❌ | Verify TLS certs | true | | PI_CONTROLLER_TLS_CA_CERT | ❌ | Path to CA cert | - | | PI_CONTROLLER_TIMEOUT | ❌ | Request timeout (ms) | 30000 | | LOG_LEVEL | ❌ | Logging level | info |

*Either API key or username/password required

Authentication Methods

Method 1: API Key (Recommended) ``json { "env": { "PI_CONTROLLER_URL": "https://pi-controller.local:8080", "PI_CONTROLLER_API_KEY": "your-api-key" } } ``

Method 2: Username/Password ``json { "env": { "PI_CONTROLLER_URL": "https://pi-controller.local:8080", "PI_CONTROLLER_USERNAME": "admin", "PI_CONTROLLER_PASSWORD": "secure-password" } } ``

Examples

Create and Provision Cluster

User: "Create a K3s cluster with 1 master and 2 workers"

AI uses:
1. create_cluster → Creates cluster definition
2. discover_nodes → Finds available Pi nodes
3. provision_cluster → Installs K3s on selected nodes
4. cluster://{id}/status → Monitors provisioning progress

Control GPIO Hardware

User: "Turn on the LED on GPIO pin 18"

AI uses:
1. discover_nodes → Finds the right node
2. list_gpio_devices → Locates GPIO device on pin 18
3. write_gpio_pin → Sets pin value to HIGH (1)
4. gpio://{id}/state → Confirms new state

Deploy Application

User: "Deploy nginx on the homelab cluster"

AI uses:
1. list_clusters → Finds homelab cluster
2. deploy_pod → Creates nginx pod
3. get_pod → Verifies deployment

Development

Setup

git clone https://github.com/dsyorkd/pi-controller-mcp.git
cd pi-controller-mcp
npm install

Run in Development

# Copy environment template
cp .env.example .env

# Edit .env with your pi-controller URL and credentials
nano .env

# Start in watch mode
npm run dev

Build

npm run build

Test

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests (requires running pi-controller)
npm run test:integration

Architecture

pi-controller-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Configuration loader
│   ├── client/
│   │   ├── pi-controller-client.ts  # REST API client
│   │   └── auth.ts           # Authentication
│   ├── tools/
│   │   ├── cluster.ts        # Cluster tools
│   │   ├── node.ts           # Node tools
│   │   ├── gpio.ts           # GPIO tools
│   │   ├── deployment.ts     # Deployment tools
│   │   └── ca.ts             # CA tools
│   ├── resources/
│   │   ├── cluster-status.ts # Cluster resources
│   │   ├── node-info.ts      # Node resources
│   │   ├── gpio-state.ts     # GPIO resources
│   │   └── metrics.ts        # Metrics resources
│   └── types/
│       └── pi-controller.ts  # Type definitions

Troubleshooting

Connection Issues

Error: Cannot connect to pi-controller

Solutions:

Verify PI_CONTROLLER_URL is correct
Check pi-controller is running: curl ${PI_CONTROLLER_URL}/health
Verify network connectivity
Check TLS certificate if using HTTPS

Authentication Issues

Error: Authentication failed

Solutions:

Verify credentials in .mcp.json or .env
Check user has required RBAC role
For API key: Ensure key is valid and not expired
For username/password: Verify credentials are correct

Permission Issues

Error: Forbidden: insufficient permissions

Solutions:

Tools require different RBAC roles:

Read operations: viewer role
Write operations: operator role
Lifecycle operations: admin role

Check user role: See pi-controller documentation

Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open Pull Request

See CONTRIBUTING.md for development guidelines.

Related Projects

pi-controller - Main control plane
kubes-aura - Web UI
pi-agent - Node agent (part of pi-controller)

License

MIT License - see LICENSE file for details

Support

---

Built with ❤️ for the Raspberry Pi and AI community

pi-controller-mcp