home / mcp / homelab mcp server

Homelab MCP Server

Provides multi-host Docker management across Unraid, Proxmox, and bare-metal hosts via HTTP or stdio transports.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jmagar-homelab-mcp": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "HOST": "127.0.0.1 (default)",
        "PORT": "3000 (default)"
      }
    }
  }
}

You run a centralized MCP server that can manage Docker containers across multiple homelab hosts. It auto-detects local Docker when available, lets you start/stop/restart containers across hosts, fetch logs with filters, monitor resources in real-time, and search or inspect containers with a unified interface. It supports both local (stdio) usage with Claude Code and remote HTTP access for multi-client setups.

How to use

You can connect to the MCP server in two ways: via Claude Code using a local stdio transport, or via HTTP for remote access. Use the Claude Code flow to run commands directly from your editor, or run the HTTP server to expose the MCP API over the network for other clients. Typical operations include listing containers, starting or stopping containers on any host, viewing container logs with time-based and grep filters, and monitoring CPU, memory, network, and I/O in real time. The server automatically discovers your local Docker if available, and you can filter results by host or tags to manage a large fleet.

In Claude Code you load an MCP server configuration that points to your local startup command and config file path. Then you can issue commands like: list containers, restart a specific container, or fetch recent error logs. In HTTP mode you start the server, then access the MCP endpoint at the given URL to perform the same operations from any remote client.

How to install

Prerequisites: ensure you have Node.js installed on your machine. You will also need a valid configuration for connecting to your Docker hosts (either via the local Docker socket or over TCP). Then install dependencies, build, and run the server.

Step 1: Install dependencies
```
npm install

Step 2: Build the server
```
npm run build

Step 3: Run in HTTP mode for remote access ``node dist/index.js --http`` Server URL (default): http://127.0.0.1:3000/mcp Health check: http://127.0.0.1:3000/health

Configuration

Configure the MCP server to connect to your hosts. You can rely on automatic local Docker detection if a Docker socket is present, or specify hosts explicitly in a config file.

Example configuration (hosts array):
```
{
  "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"
    }
  ]
}

If you run the server on the same machine with Docker, it can auto-add a local host by detecting the Docker socket at /var/run/docker.sock and using your machine's hostname as the host name. This makes it usable out of the box for local Docker without extra config.

Security and hosting notes

Exposing the Docker API over TCP without TLS can be insecure. Use TLS or limit access to trusted networks when enabling remote HTTP access.

When running in HTTP mode on a network, consider securing the MCP endpoint with authentication or network ACLs to prevent unauthorized access.

Troubleshooting

If the server fails to start in HTTP mode, verify that the port 3000 is not in use and that Node.js can bind to the address. Check that Docker hosts are reachable and that you have correct permissions to access their Docker APIs.

If local Docker is not detected, ensure /var/run/docker.sock exists and is readable by the process. You can force host definitions in the config file to connect to remote Docker endpoints.

Tools and capabilities overview

Your MCP server provides a set of tools to manage and inspect containers across all hosts. Each tool is designed to operate on multiple hosts and can filter results by container name, image, state, and labels.

Available tools

homelab_list_containers

List containers with filtering by state, name, image, labels across all hosts

homelab_container_action

Start/stop/restart/pause/unpause containers across hosts

homelab_get_logs

Retrieve container logs with time and grep filters across hosts

homelab_container_stats

Get CPU, memory, network, I/O statistics in real time across hosts

homelab_inspect_container

Detailed container configuration and state information for any container

homelab_host_status

Check connectivity and container counts per host

homelab_search_containers

Search containers by name, image, or labels across all hosts

homelab_docker_info

Get Docker version, resources, and system info per host

homelab_docker_df

Get Docker disk usage (images, containers, volumes, cache) per host

homelab_prune

Remove unused Docker resources (requires force=true) across hosts

homelab_host_resources

Get host CPU, memory, disk usage via SSH