Lawiak/docker-mcp-raspi

Docker MCP Server Setup for Raspberry Pi

This package provides everything needed to set up and replicate a Docker MCP (Model Context Protocol) server on Raspberry Pi systems for remote Docker management through Claude Desktop and other MCP clients.

🎯 Manage Docker containers on your Raspberry Pi using natural language through Claude Desktop!

🚀 Quick Start

For Raspberry Pi Installation

# 1. Copy this package to your Raspberry Pi
scp -r docker-mcp-raspi/ pi@YOUR_RASPI_IP:~/

# 2. SSH to your Raspberry Pi
ssh pi@YOUR_RASPI_IP

# 3. Run the installation script
cd ~/docker-mcp-raspi/scripts
chmod +x install-mcp-server.sh
./install-mcp-server.sh

For Client Configuration

# Configure Claude Desktop to connect to your MCP server
cd docker-mcp-raspi/config
chmod +x configure-client.sh
./configure-client.sh YOUR_RASPI_IP

📁 Package Structure

docker-mcp-raspi/
├── README.md                           # This file
├── scripts/                            # Server installation scripts
│   ├── install-mcp-server.sh          # Main installation script
│   ├── mcp-tcp-bridge.py              # TCP bridge for remote access
│   ├── mcp-server-wrapper.sh          # MCP server wrapper
│   ├── start-mcp-server.sh            # Daemon startup script
│   └── test-mcp-connection.py          # Connection test script
├── templates/                          # Configuration templates
│   ├── mcp-tcp-bridge.service         # Systemd service for TCP bridge
│   ├── mcp-server-docker.service      # Systemd service for MCP server
│   ├── claude-desktop-config.json     # Claude Desktop configuration
│   └── test-connection.py             # Client test script template
├── config/                            # Client configuration
│   ├── configure-client.sh            # Client configuration script
│   └── claude_desktop_config.json     # Pre-configured Claude Desktop config
└── docs/                              # Documentation
    └── MCP-Docker-Setup-Documentation.md  # Detailed documentation

🔧 Prerequisites

Raspberry Pi Requirements

• Raspberry Pi 4 or 5 (4GB+ RAM recommended)
• Raspberry Pi OS (Debian 11+ or Ubuntu 20.04+)
• Docker installed and running
• SSH access configured
• Network connectivity
• At least 2GB free disk space

Client Requirements

• SSH access to Raspberry Pi
• Claude Desktop installed
• Python 3.6+ (for testing)
• Network access to Raspberry Pi

🛠️ Installation Process

Step 1: Prepare Raspberry Pi

1. Install Docker (if not already installed):

   curl -sSL https://get.docker.com | sh
   sudo usermod -aG docker pi
   # Log out and back in for group changes to take effect
   

2. Verify Docker installation:

   docker --version
   docker run hello-world
   

Step 2: Install MCP Server

1. Transfer installation package:

   scp -r docker-mcp-raspi/ pi@YOUR_RASPI_IP:~/
   

2. Run installation script:

   ssh pi@YOUR_RASPI_IP
   cd ~/docker-mcp-raspi/scripts
   chmod +x install-mcp-server.sh
   ./install-mcp-server.sh
   

3. Verify installation:

   sudo systemctl status mcp-tcp-bridge.service
   netstat -tlpn | grep 8765
   

Step 3: Configure Clients

1. Run client configuration:

   cd docker-mcp-raspi/config
   chmod +x configure-client.sh
   ./configure-client.sh YOUR_RASPI_IP
   

2. Test connection:

   python3 ~/test-mcp-connection.py YOUR_RASPI_IP
   

3. Restart Claude Desktop to load the new configuration

🔌 Connection Methods

Method 1: SSH Connection (Recommended)

The MCP server uses SSH to securely connect to the Raspberry Pi and run Docker commands.

Claude Desktop Configuration:

{
  "mcpServers": {
    "docker-server-raspi": {
      "command": "ssh",
      "args": [
        "pi@YOUR_RASPI_IP",
        "docker", "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "mcp-server-docker:latest"
      ]
    }
  }
}

Method 2: Direct TCP Connection

For advanced users, direct TCP connection to port 8765 is available through the TCP bridge.

🐳 Available Docker Tools

The MCP server provides 19 Docker management tools:

Container Management

• docker_container_create - Create new containers
• docker_container_run - Run containers with options
• docker_container_start - Start stopped containers
• docker_container_stop - Stop running containers
• docker_container_logs - View container logs
• docker_container_remove - Remove containers
• docker_container_list - List all containers

Image Management

• docker_image_list - List Docker images
• docker_image_pull - Pull images from registry
• docker_image_push - Push images to registry
• docker_image_build - Build images from Dockerfile
• docker_image_remove - Remove images

Network & Volume Management

• docker_network_list - List Docker networks
• docker_network_create - Create networks
• docker_network_remove - Remove networks
• docker_volume_list - List volumes
• docker_volume_create - Create volumes
• docker_volume_remove - Remove volumes

Compose Operations

• docker_compose_up - Start multi-container applications
• docker_compose_down - Stop multi-container applications

🎯 Usage Examples

Once configured, you can use natural language commands in Claude Desktop:

• "List all Docker containers on my Raspberry Pi"
• "Start a new nginx container with port 80 exposed"
• "Show logs for the teslamate container"
• "Pull the latest Python 3.11 image"
• "Create a new Docker network called 'myapp'"
• "Stop all running containers"
• "Remove unused Docker images"

🔧 Management Commands

Service Management

# Check service status
sudo systemctl status mcp-tcp-bridge.service

# View logs
sudo journalctl -u mcp-tcp-bridge.service -f
tail -f /var/log/mcp-tcp-bridge.log

# Restart services
sudo systemctl restart mcp-tcp-bridge.service

Manual Operation

# Run MCP server manually
cd /home/pi/mcp-server
./mcp-server-wrapper.sh

# Test TCP bridge
python3 mcp-tcp-bridge.py

# Start daemon mode
./start-mcp-server.sh

🚨 Troubleshooting

Common Issues

1. Port 8765 not accessible

   • Check firewall rules: sudo ufw status
   • Verify service is running: sudo systemctl status mcp-tcp-bridge.service

2. SSH connection fails

   • Test SSH manually: ssh pi@YOUR_RASPI_IP
   • Check SSH keys: ssh-add -l

3. Docker permission denied

   • Verify user in docker group: groups pi
   • Re-login after adding to group

4. Service won't start

   • Check logs: sudo journalctl -u mcp-tcp-bridge.service
   • Verify Docker is running: systemctl status docker

5. MCP server not responding

   • Check container logs: docker logs mcp-server-docker-bridge
   • Restart services: sudo systemctl restart mcp-tcp-bridge.service

Log Files

• TCP Bridge: /var/log/mcp-tcp-bridge.log
• MCP Server: /var/log/mcp-server.log
• Installation: /tmp/mcp-install.log
• Systemd: sudo journalctl -u mcp-tcp-bridge.service

🔒 Security Considerations

• SSH Key Authentication: Use key-based authentication instead of passwords
• Network Security: The MCP server has full Docker socket access
• Firewall: Consider restricting access to port 8765
• VPN: Use VPN for remote access outside local network
• Container Isolation: MCP server runs in Docker containers for isolation

🔄 Replication Steps

To replicate this setup on additional Raspberry Pis:

1. Copy the complete package:

   scp -r docker-mcp-raspi/ pi@NEW_RASPI_IP:~/
   

2. Run installation:

   ssh pi@NEW_RASPI_IP
   cd ~/docker-mcp-raspi/scripts
   ./install-mcp-server.sh
   

3. Configure clients for the new Raspberry Pi:

   ./configure-client.sh NEW_RASPI_IP
   

4. Update Claude Desktop configuration to include multiple servers:

   {
     "mcpServers": {
       "docker-server-raspi1": {
         "command": "ssh",
         "args": ["pi@192.168.2.205", "docker", "run", "-i", "--rm", "-v", "/var/run/docker.sock:/var/run/docker.sock", "mcp-server-docker:latest"]
       },
       "docker-server-raspi2": {
         "command": "ssh",
         "args": ["pi@192.168.2.206", "docker", "run", "-i", "--rm", "-v", "/var/run/docker.sock:/var/run/docker.sock", "mcp-server-docker:latest"]
       }
     }
   }
   

📊 Performance Optimization

• Resource Monitoring: Monitor CPU and memory usage during operations
• Container Cleanup: Regularly clean up unused containers and images
• Network Optimization: Use Ethernet for better performance
• Storage: Use SSD for better I/O performance

🔄 Updates and Maintenance

Updating MCP Server

# Rebuild Docker image
cd /tmp
git clone https://github.com/ckreiling/mcp-server-docker.git
cd mcp-server-docker
docker build -t mcp-server-docker:latest .

# Restart services
sudo systemctl restart mcp-tcp-bridge.service

Backup Configuration

# Create backup
tar -czf mcp-server-backup.tar.gz /home/pi/mcp-server /etc/systemd/system/mcp-*

# Restore backup
tar -xzf mcp-server-backup.tar.gz -C /
sudo systemctl daemon-reload
sudo systemctl enable mcp-tcp-bridge.service

🤝 Contributing

Feel free to contribute improvements to this setup:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📝 License

This project is provided as-is for educational and personal use. Please refer to the individual component licenses for specific terms.

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review log files for error messages
3. Test individual components
4. Consult the detailed documentation in docs/

Created: July 16, 2025
Version: 1.0.0
Tested on: Raspberry Pi 4 & 5 with Docker 28.2.2