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

Tool	Description
homelab_list_containers	List containers with filtering by state, name, image, labels
homelab_container_action	Start/stop/restart/pause/unpause containers
homelab_get_logs	Retrieve container logs with time and grep filters
homelab_container_stats	Get CPU, memory, network, I/O statistics
homelab_inspect_container	Detailed container configuration and state
homelab_host_status	Check connectivity and container counts per host
homelab_search_containers	Search containers by name, image, or labels
homelab_docker_info	Get Docker version, resources, and system info per host
homelab_docker_df	Get Docker disk usage (images, containers, volumes, cache)
homelab_prune	Remove unused Docker resources (requires force=true)
homelab_host_resources	Get host CPU, memory, disk usage via SSH

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

Field	Type	Description
name	string	Unique identifier for the host
host	string	Hostname or IP address
port	number	Docker API port (default: 2375)
protocol	"http" | "https"	Connection protocol
dockerSocketPath	string	Path to Docker socket (for local connections)
tags	string[]	Optional tags for filtering

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