mcp-homelab-server

MCP Homelab Server 🏠

Model Context Protocol server for homelab management Give AI agents access to your homelab: Docker, Ollama, system stats, and more.

What Is This?

An MCP (Model Context Protocol) server that exposes homelab tools to AI agents like Claude, GPT, or any MCP-compatible client. Instead of writing scripts yourself, just ask your AI agent to manage your infrastructure.

Example conversations:

• "List all running Docker containers"
• "How much RAM is Ollama using?"
• "Pull the llama3 model"
• "Show me disk usage on the server"

Tools Provided

Docker Management

| Tool | Description | |------|-------------| | docker_ps | List running containers | | docker_logs | Get container logs | | docker_restart | Restart a container | | docker_stop | Stop a container | | docker_stats | Resource usage (CPU, RAM, network) |

Ollama / LLM Management

| Tool | Description | |------|-------------| | ollama_list | List installed models | | ollama_pull | Pull a new model | | ollama_ps | Show running models and memory usage | | ollama_generate | Run a quick inference test |

System Monitoring

| Tool | Description | |------|-------------| | system_stats | CPU, RAM, disk, uptime | | disk_usage | Detailed disk usage by mount | | network_status | Network interfaces and connections | | process_top | Top processes by CPU/RAM |

Quick Start

With Claude Desktop / Cursor / any MCP client

Add to your MCP client configuration:

{
  "mcpServers": {
    "homelab": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-homelab"]
    }
  }
}

With OpenClaw

{
  "mcpServers": {
    "homelab": {
      "command": "python3",
      "args": ["path/to/mcp-homelab-server/src/server.py"]
    }
  }
}

Standalone (for testing)

git clone https://github.com/Proto-labs-rnd/mcp-homelab-server.git
cd mcp-homelab-server
pip install -r requirements.txt
python3 src/server.py

Requirements

• Python 3.10+
• Docker (for Docker tools)
• Ollama (for LLM tools, optional)
• Linux/macOS (system stats rely on standard Unix tools)

Architecture

MCP Client (Claude, Cursor, OpenClaw, etc.)
        │
        ▼
┌─────────────────────┐
│  MCP Server (stdio)  │
│  ┌───────────────┐  │
│  │ Docker Tools  │  │
│  │ Ollama Tools  │  │
│  │ System Tools  │  │
│  └───────────────┘  │
└─────────────────────┘
        │
        ▼
   Your Homelab

License

MIT