AI导哈

Docker容器管理服务

Homelab MCP Server是一个用于在家庭实验室环境中管理Docker容器的服务，支持容器生命周期管理、日志查看和资源监控等功能。

  • by shcizo
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 shcizo/homelab-mcp-server

使用说明

Homelab MCP服务器

MCP（模型上下文协议）服务器，用于在家庭实验室环境中管理Docker容器。允许Claude检查和管理您的Docker容器、映像、卷和组合项目。

这是什么？

这是一个MCP服务器，它使Claude（或其他MCP客户端）能够：

  • 列出Docker容器及其状态
  • 获取容器日志
  • 管理容器生命周期（启动/停止/重新启动）
  • 检查Docker Compose项目
  • 监控资源使用情况
  • 还有更多！

需求

  • Python 3.10+
  • Docker已安装并正在运行
  • uv （Python包管理器）或 pip

安装

  1. 克隆此存储库：
git clone <your-repo-url>
cd homelab-mcp-server
  1. 安装依赖项：
# Using uv (recommended)
uv sync --all-extras

# Or using pip
pip install -e ".[dev]"
  1. 测试Docker连接：
uv run python test_connection.py

Docker安装（替代方案）

您可以在Docker容器中运行MCP服务器，而不是在本地安装。这对于隔离和更容易的部署很有用。

选项1：使用GitHub容器注册表中的预构建映像（推荐）

最简单的入门方法是使用GitHub容器注册表中的预构建映像：

# Pull the latest image
docker pull ghcr.io/shcizo/homelab-mcp-server:latest

# Run the container
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/shcizo/homelab-mcp-server:latest

可用标签：

  • latest -主分支的最新构建
  • v1.0.0, v1.0, v1 -语义版本标签（发布时）
  • main-<sha> -主要分支机构的具体承诺

对于GHCR的Claude Code：

{
  "mcpServers": {
    "homelab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "ghcr.io/shcizo/homelab-mcp-server:latest"
      ]
    }
  }
}

选项2：在本地构建Docker镜像

如果你想自己建立形象：

docker build -t homelab-mcp-server .

运行本地构建的容器

如果您在本地构建了映像，请使用以下命令运行它：

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name homelab-mcp \
  homelab-mcp-server

注： 替换 homelab-mcp-server 随着 ghcr.io/shcizo/homelab-mcp-server:latest 使用GHCR的预构建图像。

重要提示：

  • 这 -v /var/run/docker.sock:/var/run/docker.sock 标志赋予容器访问主机Docker守护进程的权限
  • 这使容器可以完全控制主机系统上的Docker
  • 在某些系统上，您可能需要调整Docker套接字权限或使用 --user root 用于测试
  • 容器以非root用户身份运行(mcp)为了安全

测试Docker容器

测试容器是否正常工作（使用 ghcr.io/shcizo/homelab-mcp-server:latest 或 homelab-mcp-server 本地建造）：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/shcizo/homelab-mcp-server:latest

Docker权限

如果你在访问Docker套接字时遇到权限错误，你有几个选择：

选项1：以root身份运行（临时/仅测试）

docker run -i --rm --user root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/shcizo/homelab-mcp-server:latest

选项2：匹配主机docker组GID（用于本地构建） 查找主机的docker组GID：

getent group docker | cut -d: -f3

然后使用该GID进行重建：

docker build --build-arg DOCKER_GID=<your-gid> -t homelab-mcp-server .

选项3：调整主机上的套接字权限（不推荐）

sudo chmod 666 /var/run/docker.sock

选项3：使用Docker Compose

为了简化容器管理，您可以使用Docker Compose。A. docker-compose.yml 文件包含在存储库中：

version: '3.8'

services:
  homelab-mcp:
    image: ghcr.io/shcizo/homelab-mcp-server:latest
    container_name: homelab-mcp
    stdin_open: true
    user: root  # Required for Docker socket access
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

注： 容器运行方式如下 root 以确保对Docker套接字的访问。这是必要的，因为Docker套接字通常需要主机上的root或Docker组权限。

启动服务：

docker-compose up -d

查看日志：

docker-compose logs -f homelab-mcp

停止服务：

docker-compose down

拉取最新图像并重新启动：

docker-compose pull && docker-compose up -d

Docker Compose的优点：

  • 更简单的服务管理（启动/停止/重新启动）
  • 故障或系统重新启动时自动重新启动
  • 简单配置文件
  • 易于添加到现有的组合堆栈中

远程访问模式（HTTP/SSE）

MCP服务器支持两种传输模式：

  • stdio模式 （默认）：对于本地通信，Claude Code直接运行容器
  • HTTP/SSE模式：用于远程访问-在homelab服务器上运行，从任何地方连接

启用远程访问模式，使用提供的docker-compose.yml配置：

# On your homelab server
docker compose up -d

docker-compose.yml已预先配置为HTTP/SSE模式：

services:
  homelab-mcp:
    environment:
      - MCP_TRANSPORT=http
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8080
    ports:
      - "8080:8080"

配置Claude Code以远程连接：

将此添加到您的Claude Code MCP配置中(~/.claude/mcp.json 或 %APPDATA%\.claude\mcp.json 在Windows上）：

{
  "mcpServers": {
    "homelab": {
      "url": "http://your-homelab-ip:8080/sse"
    }
  }
}

替换 your-homelab-ip 使用您的家庭实验室服务器的IP地址（例如。， 192.168.1.100).

验证它是否正在运行：

# Check server logs
docker logs homelab-mcp

# Test endpoint
curl -I http://localhost:8080/sse

安全注意事项：

  • 默认情况下，HTTP/SSE模式没有身份验证
  • 仅在受信任的网络（您的家庭网络）上公开
  • 对于互联网曝光，使用带有身份验证的反向代理（nginx、Caddy、Traefik）
  • 考虑使用VPN（Tailscale、WireGuard）进行安全的远程访问

Claude代码的配置

将此添加到您的Claude Code MCP配置中。您可以通过Claude Code设置或手动编辑它：

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/samuelenocsson/dev/homelab-mcp-server",
        "python",
        "src/homelab_mcp/server.py"
      ]
    }
  }
}

此配置的作用：

  • command: "uv" -使用uv运行服务器
  • --directory -为项目设置工作目录
  • python src/homelab_mcp/server.py -运行MCP服务器

替代方案：使用Docker（推荐）

如果你更喜欢在Docker中运行服务器，请使用以下配置：

{
  "mcpServers": {
    "homelab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "ghcr.io/shcizo/homelab-mcp-server:latest"
      ]
    }
  }
}

Docker配置说明：

  • 使用GitHub容器注册表中的预构建映像（无需本地构建）
  • 这 -i 标志启用stdin/stdout通信的交互模式
  • 这 --rm 标志每次使用后都会移除容器
  • 如果遇到权限错误，请调整Docker套接字权限
  • 要使用本地生成的映像，请替换 ghcr.io/shcizo/homelab-mcp-server:latest 随着 homelab-mcp-server

添加此内容后，重新启动Claude Code以加载新服务器。

测试服务器

选项1：使用Claude代码进行测试

  1. 添加上面的配置
  2. 重新启动Claude代码
  3. 在聊天中，问：“你能列出我的Docker容器吗？”
  4. 克劳德应该使用 list_containers 工具并显示您的容器

选项2：手动测试

运行Docker连接测试：

uv run python test_connection.py

可用工具

ping

简单的测试工具，用于验证服务器是否正常工作。

用途： “Ping家庭实验室服务器”

list_containers

列出所有Docker容器及其状态。

参数：

  • all （boolean，可选）：显示所有容器（默认值：true）。设置为false仅显示正在运行的容器。

使用示例：

  • “列出我的所有Docker容器”
  • “仅显示正在运行的容器”
  • “我的家庭实验室里正在运行什么容器？”

发展

项目结构

homelab-mcp-server/
├── src/
│   └── homelab_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server
├── tests/                      # Tests (coming soon)
├── pyproject.toml              # Dependencies & config
├── test_connection.py          # Docker connection test
└── README.md

手动运行服务器

uv run python src/homelab_mcp/server.py

服务器使用JSON-RPC通过stdin/stdout进行通信，因此手动运行它不会显示太多输出，除非您发送格式正确的MCP消息。

添加新工具

  1. 将工具元数据添加到 list_tools() 功能在 server.py
  2. 在中实现工具逻辑 call_tool() 函数
  3. 使用Claude Code进行测试或编写单元测试

运作原理

MCP架构

┌─────────────┐         MCP Protocol        ┌──────────────────┐
│   Claude    │ ←──────────────────────────→ │   This Server    │
│  (Client)   │    JSON-RPC over stdio      │   (homelab-mcp)  │
└─────────────┘                              └──────────────────┘
                                                      ↓
                                              ┌──────────────────┐
                                              │  Docker Engine   │
                                              │  (docker-py SDK) │
                                              └──────────────────┘

通信流

  1. Claude发送请求 → 通过stdin发送JSON-RPC消息
  2. MCP服务器接收 → 通往合适工具搬运员的路线
  3. 服务器调用Docker API → 使用docker py SDK
  4. Docker响应 → 容器信息、日志、状态等。
  5. 服务器格式响应 → 文本包含结果
  6. 克劳德收到回复 → 向用户显示

关键组件

服务器(server.py)

  • 使用官方SDK实现MCP协议
  • 通过以下方式声明可用工具 list_tools()
  • 通过执行工具调用 call_tool()
  • 管理Docker客户端连接

Docker客户端(docker.from_env())

  • Docker官方Python SDK
  • 自动连接到Docker守护进程（socket/env）
  • 提供完整的Docker API访问

MCP-SDK(mcp 包装）

  • 处理所有协议细节（JSON-RPC、验证）
  • 类型安全工具定义
  • stdin/stdout通信

后续步骤

请参阅 GitHub问题 对于计划中的功能：

  • 容器日志获取和搜索
  • Docker Compose项目管理
  • 卷和存储管理
  • 图像管理和更新
  • 资源监控（CPU、内存、网络）
  • 集装箱健康检查
  • 还有30多个功能！

许可证

麻省理工学院

贡献

欢迎投稿！请先打开一个问题，讨论您想更改的内容。

相关 MCP