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

Related MCP server: SystemPrompt Coding Agent

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

*Either API key or username/password required

Authentication Methods

Method 1: API Key (Recommended)

{
  "env": {
    "PI_CONTROLLER_URL": "https://pi-controller.local:8080",
    "PI_CONTROLLER_API_KEY": "your-api-key"
  }
}

Method 2: Username/Password

{
  "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:

1. Verify PI_CONTROLLER_URL is correct

2. Check pi-controller is running: curl ${PI_CONTROLLER_URL}/health

3. Verify network connectivity

4. Check TLS certificate if using HTTPS

Authentication Issues

Error: Authentication failed

Solutions:

1. Verify credentials in .mcp.json or .env

2. Check user has required RBAC role

3. For API key: Ensure key is valid and not expired

4. For username/password: Verify credentials are correct

Permission Issues

Error: Forbidden: insufficient permissions

Solutions:

1. Tools require different RBAC roles:

   • Read operations: viewer role

   • Write operations: operator role

   • Lifecycle operations: admin role

2. Check user role: See pi-controller documentation

Contributing

1. Fork the repository

2. Create feature branch: git checkout -b feature/amazing-feature

3. Commit changes: git commit -m 'Add amazing feature'

4. Push to branch: git push origin feature/amazing-feature

5. 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

• 📖 Documentation

• 🐛 Issue Tracker

• 💬 Discussions

Built with ❤️ for the Raspberry Pi and AI community