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, pull, recreate containers

• Docker Compose: Full project management (up, down, restart, logs, build, pull, recreate)

• Image operations: List, pull, build, and remove Docker images

• 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 (with summary mode)

• Pagination & filtering: All list operations support limits, offsets, and filtering

• Dual transport: stdio for Claude Code, HTTP for remote access

• SSH support: Execute commands on remote hosts for resource monitoring

Tool

The server provides a single unified tool homelab with multiple actions and subactions:

Container Operations (action: "container")

Docker Compose Operations (action: "compose")

Host Operations (action: "host")

Docker System Operations (action: "docker")

Image Operations (action: "image")

Example Usage

Installation

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

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

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

Resource Limits & Defaults

Enabling Docker API on Hosts

Unraid

Docker API is typically available at port 2375 by default.

Standard Docker (systemd)

Edit /etc/docker/daemon.json:

Or override the systemd service:

⚠️ 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:

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

Then in Claude Code:

HTTP Mode

For remote access or multi-client scenarios:

Environment variables for HTTP mode:

• PORT: Server port (default: 3000)

• HOST: Bind address (default: 127.0.0.1)

CLI Help

Example Interactions

List containers

Check logs

Resource monitoring

Compose operations

Image management

Security

Path Traversal Protection (CWE-22)

The image_build tool implements strict path validation to prevent directory traversal attacks:

• Absolute paths required: All paths (context, dockerfile) must start with /

• Traversal blocked: Paths containing .. or . components are rejected

• Character validation: Only alphanumeric, dots (in filenames), hyphens, underscores, and forward slashes allowed

• Pre-execution validation: Paths validated before SSH commands are executed

Example of rejected paths:

General Security Notes

• Docker API on port 2375 is insecure without TLS

• Always use execFile for shell commands (prevents injection)

• Validate host config fields with regex

• Require force=true for destructive operations

Development

Architecture

Key Architectural Changes

Unified Tool Pattern (Commit 07fccbd, 12/18/2025):

• Consolidated 15 individual tools into a single homelab tool

• Action/subaction routing pattern for better organization

• Single entry point with type-safe parameter validation

Formatting Module (Commit 147d563):

• Extracted 40+ formatting helpers to dedicated formatters/ module

• Markdown output for all tool responses

• Consistent formatting across all operations

Docker Compose Support (Commit ec88df9):

• Full compose project lifecycle management

• Service-level operations and filtering

• Build, pull, and recreate capabilities

Discriminated Union Optimization (Commit f8e6e27, 12/24/2025):

• Migrated schema validation from O(n) sequential to O(1) discriminated union

• Uses composite action_subaction discriminator for instant schema lookup

• Achieved <0.005ms validation latency across all 30 operations

• Zero performance degradation regardless of which operation is called

Test Coverage:

• Unit tests for all services, schemas, and tools

• Integration tests for end-to-end workflows

• Performance benchmarks for schema validation

• 8 test files covering core functionality

Performance

Schema Validation

The unified tool uses Zod discriminated union for O(1) constant-time schema validation:

• Validation latency: <0.005ms average across all 30 operations

• Optimization: Discriminated union with action_subaction composite key

• Consistency: All operations perform identically fast (no worst-case scenarios)

All inputs are automatically preprocessed to inject the discriminator key, maintaining backward compatibility.

SSH Connection Pooling

All SSH operations use connection pooling for optimal performance:

• 50× faster for repeated operations

• Connections reused across compose operations

• Automatic idle timeout and health checks

• Configurable via environment variables

See docs/ssh-connection-pooling.md for details.

Key Benefits:

• Eliminate 250ms connection overhead per operation

• Support high-concurrency scenarios (configurable pool size)

• Automatic connection cleanup and health monitoring

• Zero code changes required (transparent integration)

Benchmarks

Run performance benchmarks:

Expected results:

• Worst-case validation: <0.005ms (0.003ms typical)

• Average-case validation: <0.005ms (0.003ms typical)

• Performance variance: <0.001ms (proves O(1) consistency)

License

MIT