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)

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