Which integrations are available for this server?

Manages [Docker](/mcp/servers/integrations/docker) containers across multiple homelab hosts, providing tools for container lifecycle management (start, stop, restart, pause/unpause), log retrieval, resource monitoring (CPU, memory, network, I/O), container search and inspection, and Docker system operations including disk usage analysis and resource pruning.

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):

Path in HOMELAB_CONFIG_FILE env var
./homelab.config.json (current directory)
~/.config/homelab-mcp/config.json
~/.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

Homelab MCP Server