pi-controller-mcp
Allows creation, provisioning, scaling, and deletion of K3s clusters on Raspberry Pi nodes.
Provides tools for deploying, inspecting, and deleting Kubernetes pods on the cluster.
Provides tools for discovering, registering, and managing Raspberry Pi nodes, including GPIO pin control and hardware monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pi-controller-mcp Create a 3-node K3s cluster called 'homelab'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 definitionlist_clusters- List all clustersget_cluster_status- Get detailed cluster statusprovision_cluster- Provision K3s on nodesscale_cluster- Scale cluster nodesdelete_cluster- Delete cluster
Node Management
discover_nodes- List discovered Raspberry Pi nodesget_node_info- Get node details and hardware inforegister_node- Manually register a nodeprovision_node- Provision K3s on single nodedeprovision_node- Remove K3s from node
GPIO Control
list_gpio_devices- List all GPIO devicescreate_gpio_device- Register GPIO deviceread_gpio_pin- Read pin valuewrite_gpio_pin- Write to pin (HIGH/LOW)reserve_gpio_pin- Reserve pin for exclusive userelease_gpio_pin- Release reservationget_gpio_readings- Get historical readingsdelete_gpio_device- Remove GPIO device
Deployment
deploy_pod- Deploy Kubernetes podget_pod- Get pod informationdelete_pod- Delete pod
Certificate Authority
initialize_ca- Initialize CAissue_certificate- Issue new certificatelist_certificates- List all certificatesrevoke_certificate- Revoke certificate
Available Resources
Resources provide AI with real-time context about your clusters:
cluster://{cluster_id}/status- Cluster health and metricscluster://{cluster_id}/nodes- Node list with statusnode://{node_id}/info- Hardware specs and capabilitiesnode://{node_id}/metrics- CPU, memory, temperaturenode://{node_id}/gpio- GPIO devices on nodegpio://{gpio_id}/state- Current pin statesystem://health- Overall system health
Configuration
Environment Variables
Variable | Required | Description | Default |
| ā | Pi-controller API URL | - |
| ā ļø* | API key for auth | - |
| ā ļø* | Username for auth | - |
| ā ļø* | Password for auth | - |
| ā | Verify TLS certs |
|
| ā | Path to CA cert | - |
| ā | Request timeout (ms) |
|
| ā | Logging level |
|
*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 progressControl 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 stateDeploy 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 deploymentDevelopment
Setup
git clone https://github.com/dsyorkd/pi-controller-mcp.git
cd pi-controller-mcp
npm installRun 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 devBuild
npm run buildTest
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests (requires running pi-controller)
npm run test:integrationArchitecture
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 definitionsTroubleshooting
Connection Issues
Error: Cannot connect to pi-controller
Solutions:
Verify
PI_CONTROLLER_URLis correctCheck pi-controller is running:
curl ${PI_CONTROLLER_URL}/healthVerify network connectivity
Check TLS certificate if using HTTPS
Authentication Issues
Error: Authentication failed
Solutions:
Verify credentials in
.mcp.jsonor.envCheck 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:
viewerroleWrite operations:
operatorroleLifecycle operations:
adminrole
Check user role: See pi-controller documentation
Contributing
Fork the repository
Create feature branch:
git checkout -b feature/amazing-featureCommit changes:
git commit -m 'Add amazing feature'Push to branch:
git push origin feature/amazing-featureOpen 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
Available Tools
14 toolscreate_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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.2MIT
- AlicenseNot gradedqualityFmaintenanceAn MCP server that orchestrates AI coding assistants (Claude Code CLI and Gemini CLI) to perform complex programming tasks autonomously, allowing remote control of your local development environment from anywhere.140MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.19Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants safely inspect and operate on Kubernetes clusters through natural conversation.MIT