Raspberry Pi的Docker MCP服务器设置
此软件包提供了在Raspberry Pi系统上设置和复制Docker MCP（模型上下文协议）服务器所需的一切，以便通过Claude Desktop和其他MCP客户端进行远程Docker管理。
🎯 通过Claude Desktop使用自然语言管理Raspberry Pi上的Docker容器！
🚀 快速开始
用于Raspberry Pi安装
# 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用于客户端配置
# 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📁 封装结构
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🔧 先决条件
Raspberry Pi要求
- Raspberry Pi 4或5（建议使用4GB+RAM）
- Raspberry Pi操作系统（Debian 11+或Ubuntu 20.04+）
- Docker已安装并正在运行
- 已配置SSH访问
- 网络连接
- 至少2GB的可用磁盘空间
客户要求
- SSH访问Raspberry Pi
- 已安装Claude Desktop
- Python 3.6+（用于测试）
- Raspberry Pi的网络访问
🛠️ 安装过程
第一步：准备Raspberry Pi
- 安装Docker （如果尚未安装）：
curl -sSL https://get.docker.com | sh
sudo usermod -aG docker pi
# Log out and back in for group changes to take effect- 验证Docker安装:
docker --version
docker run hello-world步骤2：安装MCP服务器
- 转移安装包:
scp -r docker-mcp-raspi/ pi@YOUR_RASPI_IP:~/- 运行安装脚本:
ssh pi@YOUR_RASPI_IP
cd ~/docker-mcp-raspi/scripts
chmod +x install-mcp-server.sh
./install-mcp-server.sh- 验证安装:
sudo systemctl status mcp-tcp-bridge.service
netstat -tlpn | grep 8765步骤3：配置客户端
- 运行客户端配置:
cd docker-mcp-raspi/config
chmod +x configure-client.sh
./configure-client.sh YOUR_RASPI_IP- 测试连接:
python3 ~/test-mcp-connection.py YOUR_RASPI_IP- 重新启动克劳德桌面 加载新配置
🔌 连接方法
方法1:SSH连接（推荐）
MCP服务器使用SSH安全地连接到Raspberry Pi并运行Docker命令。
Claude桌面配置：
{
"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"
]
}
}
}方法2：直接TCP连接
对于高级用户，可以通过TCP网桥直接连接到端口8765。
🐳 可用的Docker工具
MCP服务器提供了19个Docker管理工具：
容器管理
docker_container_create-创建新容器docker_container_run-使用选项运行容器docker_container_start-启动已停止的容器docker_container_stop-停止运行容器docker_container_logs-查看容器日志docker_container_remove-移除容器docker_container_list-列出所有容器
图像管理
docker_image_list-列出Docker镜像docker_image_pull-从注册表中提取图像docker_image_push-将图像推送到注册表docker_image_build-从Dockerfile构建映像docker_image_remove-删除图像
网络和卷管理
docker_network_list-列出Docker网络docker_network_create-创建网络docker_network_remove-删除网络docker_volume_list-列出卷docker_volume_create-创建卷docker_volume_remove-删除卷
编写操作
docker_compose_up-启动多容器应用程序docker_compose_down-停止多容器应用程序
🎯 使用示例
配置后，您可以在Claude Desktop中使用自然语言命令：
- “列出我的Raspberry Pi上的所有Docker容器”
- “启动一个暴露端口80的新nginx容器”
- “显示teslamate容器的日志”
- “拉取最新的Python 3.11镜像”
- “创建一个名为‘myapp’的新Docker网络”
- “停止所有正在运行的容器”
- “删除未使用的Docker镜像”
🔧 管理命令
服务管理
# 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手动操作
# 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🚨 故障排除
常见问题
- 端口8765无法访问
- 检查防火墙规则： sudo ufw status - 验证服务是否正在运行： sudo systemctl status mcp-tcp-bridge.service
- SSH连接失败
- 手动测试SSH： ssh pi@YOUR_RASPI_IP - 检查SSH密钥： ssh-add -l
- Docker权限被拒绝
- 验证docker组中的用户： groups pi - 添加到组后重新登录
- 服务无法启动
- 检查日志： sudo journalctl -u mcp-tcp-bridge.service - 验证Docker是否正在运行： systemctl status docker
- MCP服务器没有响应
- 检查容器日志： docker logs mcp-server-docker-bridge - 重新启动服务： sudo systemctl restart mcp-tcp-bridge.service
日志文件
- TCP网桥:
/var/log/mcp-tcp-bridge.log - MCP服务器:
/var/log/mcp-server.log - 安装:
/tmp/mcp-install.log - 系统化:
sudo journalctl -u mcp-tcp-bridge.service
🔒 安全考虑
- SSH密钥认证：使用基于密钥的身份验证而不是密码
- 网络安全：MCP服务器具有完全的Docker套接字访问权限
- 防火墙：考虑限制访问端口8765
- 虚拟专用网络：使用VPN在本地网络之外进行远程访问
- 集装箱隔离：MCP服务器在Docker容器中运行以实现隔离
🔄 复制步骤
要在其他Raspberry Pis上复制此设置：
- 复制整个包:
scp -r docker-mcp-raspi/ pi@NEW_RASPI_IP:~/- 运行安装:
ssh pi@NEW_RASPI_IP
cd ~/docker-mcp-raspi/scripts
./install-mcp-server.sh- 配置客户端 对于新的Raspberry Pi：
./configure-client.sh NEW_RASPI_IP- 更新Claude桌面配置 包括多个服务器：
{
"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"]
}
}
}📊 性能优化
- 资源监控：监控操作过程中的CPU和内存使用情况
- 集装箱清理：定期清理未使用的容器和图像
- 网络优化：使用以太网以获得更好的性能
- 存储：使用SSD以获得更好的I/O性能
🔄 更新和维护
更新MCP服务器
# 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备份配置
# 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🤝 贡献
请随时对此设置进行改进：
- 分叉存储库
- 创建功能分支
- 提交您的更改
- 推到分支
- 创建拉取请求
📝 许可证
本项目按原样提供，供教育和个人使用。请参阅各个组件许可证以了解具体条款。
🆘 支持
对于问题和疑问：
- 检查故障排除部分
- 查看日志文件中的错误消息
- 测试单个组件
- 请参阅中的详细文档
docs/
______________________________________________________________________
创建：2025年7月16日\ 版本: 1.0.0\ 测试于：使用Docker 28.2.2的Raspberry Pi 4和5