Skip to main content
Glama

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

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.

License

MIT License - see LICENSE file for details

Support


Built with ā¤ļø for the Raspberry Pi and AI community

Available Tools

14 tools
create_clusterC

Create a new K3s cluster definition

Inputs: name (required), description, k3s_version.

delete_clusterA

Delete a cluster (must be deprovisioned first)

Inputs: cluster_id (required).

deploy_podC

Deploy a Kubernetes pod to a cluster

Inputs: pod_spec (required), cluster_id (required).

deprovision_nodeA

Remove K3s from a node and return to discovered state

Inputs: node_id (required), ssh_config.

discover_nodesB

List all discovered Raspberry Pi nodes

Inputs: role, limit, offset, status, +2 more.

get_cluster_statusA

Get detailed status of a cluster including nodes, workloads, and health

Inputs: cluster_id (required).

get_node_infoB

Get detailed information about a specific node

Inputs: node_id (required), include_gpio.

initialize_caC

Initialize the Certificate Authority for the cluster

Inputs: country (required), organization (required), validity_days.

list_clustersC

List all K3s clusters

Inputs: limit, offset.

list_gpio_devicesB

List all GPIO devices across all nodes

Inputs: limit, offset, node_id.

provision_clusterC

Provision a K3s cluster on Raspberry Pi nodes (async operation)

Inputs: cluster_id (required), ssh_config (required), master_node_id (required), k3s_config, +1 more.

provision_nodeB

Provision K3s on a single node

Inputs: role (required), node_id (required), join_token, ssh_config.

register_nodeC

Manually register a Raspberry Pi node

Inputs: name (required), ip_address (required), architecture (required), role, +1 more.

scale_clusterC

Scale a cluster by adding or removing worker nodes

Inputs: cluster_id (required), node_count (required), ssh_config.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: cluster definitions vs provisioning vs status, node discovery vs registration vs provisioning, and unique utilities like GPIO listing and CA initialization. No two tools appear to do the same thing.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (e.g., create_cluster, list_clusters, deprovision_node). This uniform structure makes the toolset predictable and easy to navigate.

    Tool Count5/5

    14 tools is well within the ideal range for a domain-specific controller. Each tool covers a necessary aspect of Raspberry Pi K3s cluster management, from node lifecycle to cluster operations.

    Completeness4/5

    The cluster and node lifecycles are well covered with create/provision/scale/delete and discover/register/provision/deprovision. Minor gaps exist in pod management (only deploy_pod, no get/delete/logs) and GPIO operations (list only), but the core workflows are complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables interaction with Kubernetes/Minikube clusters through natural language, allowing AI agents like Codename Goose to manage Kubernetes resources via the Model Context Protocol.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with Kubernetes clusters by translating natural language into kubectl and Helm operations. It allows users to query, manage, and diagnose Kubernetes resources and cluster states through a seamless integration.
      19
      Apache 2.0