homelab-mcp-server

MCP (Model Context Protocol) server for managing Docker infrastructure across multiple homelab hosts. Designed for use with Claude Code and other MCP-compatible clients.

Features

• Multi-host support: Manage containers across Unraid, Proxmox, bare metal servers, and more
• Auto-detect local Docker: Automatically adds local Docker socket if available
• Container lifecycle: Start, stop, restart, pause/unpause containers
• Log retrieval: Fetch logs with time filters, grep, and stream selection
• Resource monitoring: Real-time CPU, memory, network, and I/O statistics
• Smart search: Find containers by name, image, or labels across all hosts
• Detailed inspection: Full container configuration and state information
• Dual transport: stdio for Claude Code, HTTP for remote access

Tools

Installation

# Clone or copy the server files
cd homelab-mcp-server

# Install dependencies
npm install

# Build
npm run build

Configuration

Create a config file at one of these locations (checked in order):

1. Path in HOMELAB_CONFIG_FILE env var
2. ./homelab.config.json (current directory)
3. ~/.config/homelab-mcp/config.json
4. ~/.homelab-mcp.json

Example Config

{
  "hosts": [
    {
      "name": "unraid",
      "host": "unraid.local",
      "port": 2375,
      "protocol": "http",
      "tags": ["media", "storage"]
    },
    {
      "name": "proxmox-docker",
      "host": "192.168.1.100",
      "port": 2375,
      "protocol": "http",
      "tags": ["vms"]
    },
    {
      "name": "local",
      "host": "localhost",
      "protocol": "http",
      "dockerSocketPath": "/var/run/docker.sock"
    }
  ]
}

Copy homelab.config.example.json as a starting point:

cp homelab.config.example.json ~/.config/homelab-mcp/config.json
# or
cp homelab.config.example.json ~/.homelab-mcp.json

Note: If /var/run/docker.sock exists and isn't already in your config, it will be automatically added as a host using your machine's hostname. This means the server works out-of-the-box for local Docker without any configuration.

Host Configuration Options

Enabling Docker API on Hosts

Unraid

Docker API is typically available at port 2375 by default.

Standard Docker (systemd)

Edit /etc/docker/daemon.json:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}

Or override the systemd service:

sudo systemctl edit docker.service

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375

Security Note: Exposing Docker API without TLS is insecure. Use on trusted networks only, or set up TLS certificates.

Usage

With Claude Code

Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "homelab": {
      "command": "node",
      "args": ["/absolute/path/to/homelab-mcp-server/dist/index.js"],
      "env": {
        "HOMELAB_CONFIG_FILE": "/home/youruser/.config/homelab-mcp/config.json"
      }
    }
  }
}

Or if your config is in one of the default locations, you can skip the env entirely:

{
  "mcpServers": {
    "homelab": {
      "command": "node",
      "args": ["/absolute/path/to/homelab-mcp-server/dist/index.js"]
    }
  }
}

Then in Claude Code:

> /mcp

> List all running containers on unraid
> Restart the plex container
> Show me the logs from sonarr with errors in the last hour
> Which containers are using the most memory?

HTTP Mode

For remote access or multi-client scenarios:

# Start HTTP server
node dist/index.js --http

# Server runs on http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/health

Environment variables for HTTP mode:

• PORT: Server port (default: 3000)
• HOST: Bind address (default: 127.0.0.1)

CLI Help

node dist/index.js --help

Example Interactions

List containers

User: What containers are running on my homelab?

Claude: [calls homelab_list_containers with state="running"]

I found 47 running containers across your hosts:

 plex (unraid) - Image: linuxserver/plex | Up 3 days
 sonarr (unraid) - Image: linuxserver/sonarr | Up 3 days
 radarr (unraid) - Image: linuxserver/radarr | Up 3 days
...

Check logs

User: Show me any errors from nginx in the last hour

Claude: [calls homelab_get_logs with container_id="nginx", since="1h", grep="error"]

Found 3 error entries in nginx logs:
[14:23:15] 2024/12/15 14:23:15 [error] connect() failed...

Resource monitoring

User: Which containers are using the most CPU?

Claude: [calls homelab_container_stats]

Top CPU consumers:
| Container | Host | CPU% | Memory |
|-----------|------|------|--------|
| plex | unraid | 45.2% | 2.1 GB |
| handbrake | unraid | 23.8% | 1.4 GB |

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

homelab-mcp-server/
 src/
    index.ts          # Entry point, transport setup
    types.ts          # TypeScript interfaces
    constants.ts      # Configuration constants
    tools/
       index.ts      # MCP tool definitions
    services/
       docker.ts     # Docker API client
       ssh.ts        # SSH host resource monitoring
    schemas/
        index.ts      # Zod validation schemas
 dist/                  # Compiled JavaScript
 package.json
 tsconfig.json
 README.md

License

MIT