nbhansen/raspberry-pi-mcp-server

[95m    ____                 __                          ____  _ [0m
[95m   / __ \____ _________ / /_  ___  ____________  __/ __ \(_)[0m
[94m  / /_/ / __ `/ ___/ __ \/ __ \/ _ \/ ___/ ___/ / / / /_/ / / [0m
[94m / _, _/ /_/ (__  ) /_/ / /_/ /  __/ /  / /  / /_/ / ____/ /  [0m
[93m/_/ |_|\__,_/____/_.___/_.___/\___/_/  /_/   \__, /_/   /_/   [0m
[93m                                             /____/            [0m
[92m        MCP Server for Remote Raspberry Pi Management[0m
[91m        ═══════════════════════════════════════════[0m

Raspberry Pi MCP Server

What This Solves

Managing a Raspberry Pi remotely typically requires SSH access and manual command execution. This becomes cumbersome when you need to frequently check system status, manage services, or deploy applications. This MCP server bridges the gap by allowing AI assistants to directly interact with your Raspberry Pi through a standardized protocol.

What is MCP?

Model Context Protocol (MCP) is a standard that enables AI assistants to interact with external systems through well-defined tools. Instead of the AI trying to guess SSH commands or parse command output, MCP provides structured interfaces for specific tasks.

For example, instead of asking an AI to "run systemctl status docker", you can ask "check if Docker is running" and the MCP server handles the command execution and returns structured data that the AI can understand and act upon.

Overview

An MCP server for managing and controlling Raspberry Pi systems remotely via SSH. Provides structured access to system information, service management, Docker operations, file management, and more through a secure, validated interface.

Features

• System Management: Get system information, check disk/memory usage, monitor uptime
• Service Control: Start, stop, restart, and check status of systemd services
• Package Management: Check installed packages, verify package installation status
• File Operations: Create, read, write, delete files and list directory contents
• Docker Management: Full container lifecycle management, volume operations, compose support
• Network Tools: Check port availability and network connectivity
• Hardware Monitoring: CPU/GPU temperature monitoring (standard Pi configurations)
• Administrative Tools: Execute commands with comprehensive security validation
• Security: Input validation, command injection prevention, SSH hardening

Quick Start

Prerequisites

• Python 3.11 or higher
• SSH access to your Raspberry Pi
• MCP-compatible client (e.g., Claude Desktop)

Installation

1. Clone the repository:

git clone https://github.com/nbhansen/raspberry-pi-mcp-server.git
cd raspberry-pi-mcp-server

2. Create and activate a virtual environment:

# Create virtual environment
python -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows
# venv\Scripts\activate

3. Install dependencies:

# For users
pip install -r requirements.txt

# For developers (includes testing tools)
pip install -r requirements-dev.txt

# Or install as editable package
pip install -e .

4. Configure your connection:

cp .env.example .env
# Edit .env with your Raspberry Pi connection details

Configuration

Set these environment variables in your .env file:

• RASPBERRY_PI_HOST: IP address or hostname of your Raspberry Pi
• RASPBERRY_PI_USERNAME: SSH username (usually 'pi')
• RASPBERRY_PI_PASSWORD: SSH password (optional if using key)
• RASPBERRY_PI_SSH_KEY_PATH: Path to SSH private key (optional)
• RASPBERRY_PI_SSH_PORT: SSH port (default: 22)

Running the Server

python -m raspberry_pi_mcp_server

Available Tools (40 total)

System Tools

• test_connection: Test SSH connection to Raspberry Pi
• system_info: Get comprehensive system information
• disk_usage: Check disk space usage
• memory_usage: Check memory usage and statistics

Service Management

• service_status: Check systemd service status
• start_service: Start a systemd service
• stop_service: Stop a systemd service
• restart_service: Restart a systemd service

Package Management

• check_package_installed: Verify if a package is installed
• list_installed_packages: List installed packages (with search filter)

File Operations

• create_file: Create new files with content
• read_file: Read file contents
• append_to_file: Append content to existing files
• delete_file: Delete files
• list_directory: List directory contents with details

Docker Management

• docker_ps: List containers
• docker_pull: Pull Docker images
• docker_run: Run containers with full configuration
• docker_stop/start/restart: Container lifecycle management
• docker_logs: View container logs
• docker_remove: Remove containers
• docker_compose_up/down: Docker Compose operations
• docker_volume_create/list: Volume management
• docker_inspect: Inspect containers and images

Network Tools

• check_port: Check if ports are open/listening

Hardware Monitoring

• check_temperatures: Monitor CPU/GPU temperatures

Administrative

• execute_command: Execute arbitrary commands with security validation

🤖 Local AI Integration

This MCP server works with local AI models via LM Studio! No cloud dependencies required.

Quick Start with LM Studio

1. Install LM Studio v0.3.17+
2. Download a model: qwen2.5:7b-instruct (recommended)
3. Test without a real Pi:

   python mock_mcp_server.py
   

4. Configure LM Studio:

   {
     "mcpServers": {
       "mock-raspberry-pi": {
         "command": "python",
         "args": ["/path/to/mock_mcp_server.py"]
       }
     }
   }
   

5. Chat with your model: "What tools do you have available?"

Ready for Real Pi?

Once mock testing works, switch to the real server:

{
  "mcpServers": {
    "raspberry-pi": {
      "command": "python",
      "args": ["-m", "raspberry_pi_mcp_server"],
      "env": {
        "RASPBERRY_PI_HOST": "192.168.1.100",
        "RASPBERRY_PI_USERNAME": "pi",
        "RASPBERRY_PI_SSH_KEY_PATH": "~/.ssh/id_rsa"
      }
    }
  }
}

📁 Local AI Resources

• LOCALAI.md - Complete guide for local AI setup
• examples/lm-studio/ - LM Studio configuration and test prompts
• mock_mcp_server.py - Test server without requiring real Pi

Compatible Models

• Qwen 2.5:7B (recommended) - Excellent tool calling
• Llama 3.2 - Good performance, widely supported
• Any model with function calling support

Security

This server implements multiple security measures:

• Command injection prevention
• Input validation and sanitization
• SSH connection hardening
• Secure credential handling

Architecture

Built with hexagonal architecture for maintainability:

• Domain Layer: Core business logic and interfaces
• Application Layer: Use cases and orchestration
• Infrastructure Layer: SSH implementation
• Tools Layer: MCP tool adapters

Development

Testing

Test the server functionality with live integration tests:

# Activate virtual environment
source venv/bin/activate

# Test MCP server and connection
python test_mcp_server.py

# Test core tools (system, files, services)
python test_tools.py

# Test Docker functionality
python test_docker.py

These tests verify actual connectivity and functionality against your Raspberry Pi.

Code Quality

ruff check .
ruff format .

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.