AI导哈

Docker远程管理服务器

用于树莓派的Docker MCP服务器，支持通过Claude Desktop等客户端进行自然语言远程Docker管理。

  • by Lawiak
  • Shell
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 Lawiak/docker-mcp-raspi

使用说明

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

  1. 安装Docker （如果尚未安装）：

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

  2. 验证Docker安装:

    docker --version
docker run hello-world

步骤2：安装MCP服务器

  1. 转移安装包:

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

  2. 运行安装脚本:

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

  3. 验证安装:

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

步骤3：配置客户端

  1. 运行客户端配置:

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

  2. 测试连接:

    python3 ~/test-mcp-connection.py YOUR_RASPI_IP

  3. 重新启动克劳德桌面 加载新配置

🔌 连接方法

方法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

🚨 故障排除

常见问题

  1. 端口8765无法访问

    • 检查防火墙规则： sudo ufw status
    • 验证服务是否正在运行： sudo systemctl status mcp-tcp-bridge.service

  2. SSH连接失败

    • 手动测试SSH： ssh pi@YOUR_RASPI_IP
    • 检查SSH密钥： ssh-add -l

  3. Docker权限被拒绝

    • 验证docker组中的用户： groups pi
    • 添加到组后重新登录

  4. 服务无法启动

    • 检查日志： sudo journalctl -u mcp-tcp-bridge.service
    • 验证Docker是否正在运行： systemctl status docker

  5. 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上复制此设置：

  1. 复制整个包:

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

  2. 运行安装:

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

  3. 配置客户端 对于新的Raspberry Pi：

    ./configure-client.sh NEW_RASPI_IP

  4. 更新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

🤝 贡献

请随时对此设置进行改进：

  1. 分叉存储库
  2. 创建功能分支
  3. 提交您的更改
  4. 推到分支
  5. 创建拉取请求

📝 许可证

本项目按原样提供，供教育和个人使用。请参阅各个组件许可证以了解具体条款。

🆘 支持

对于问题和疑问：

  1. 检查故障排除部分
  2. 查看日志文件中的错误消息
  3. 测试单个组件
  4. 请参阅中的详细文档 docs/

创建：2025年7月16日
版本: 1.0.0
测试于：使用Docker 28.2.2的Raspberry Pi 4和5

相关 MCP