Homelab MCP Server

A remote MCP (Model Context Protocol) server for managing homelab infrastructure. Provides Claude with tools to monitor and manage Docker containers, OPNsense firewall, and TrueNAS storage.

Features

• 4 Capability Levels: From read-only monitoring to full management control
• Docker Management: List, monitor, control containers and Dockge stacks
• OPNsense Integration: Monitor firewall status and restart services
• TrueNAS Integration: Check pool health, manage datasets, create snapshots
• System Monitoring: CPU, memory, disk usage on the host

Quick Start

1. Prerequisites

• Docker and Docker Compose installed on target host (Wharf)
• OPNsense API credentials (optional)
• TrueNAS API key (optional)
• Node.js 20+ (for local development)

2. Setup

# Clone or copy the project to your host
cd homelab-mcp

# Copy example environment file
cp .env.example .env

# Generate a secure API key
openssl rand -hex 32

# Edit .env and add your credentials
nano .env

3. Configuration

Edit .env with your settings:

CAPABILITY_LEVEL=1        # Start with level 1 (read-only)
API_KEY=your-api-key-here # Use the generated key
PORT=3005

# OPNsense (optional)
OPNSENSE_HOST=10.0.0.1
OPNSENSE_API_KEY=your-key
OPNSENSE_API_SECRET=your-secret

# TrueNAS (optional)
TRUENAS_HOST=10.0.0.105
TRUENAS_API_KEY=your-key

4. Build and Deploy

# Build TypeScript
npm install
npm run build

# Build Docker image
docker compose build

# Start the server
docker compose up -d

# Check logs
docker compose logs -f

5. Configure Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "homelab": {
      "command": "node",
      "args": ["/path/to/homelab-mcp/dist/index.js"],
      "env": {
        "CAPABILITY_LEVEL": "1",
        "API_KEY": "your-api-key-here",
        "OPNSENSE_HOST": "10.0.0.1",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "TRUENAS_HOST": "10.0.0.105",
        "TRUENAS_API_KEY": "your-key"
      }
    }
  }
}

For remote deployment via HTTPS, see the deployment section in the plan document.

Capability Levels

Recommendation: Start with Level 1 and increase as needed.

Available Tools

Level 1 - Monitor

• docker_list_containers - List all containers
• docker_container_logs - Get container logs
• docker_container_stats - Get container CPU/memory stats
• system_info - Get host system info
• opnsense_status - Get OPNsense status
• truenas_status - Get TrueNAS pool status
• truenas_alerts - Get TrueNAS alerts

Level 2 - Operate

• docker_restart_container - Restart a container
• docker_start_container - Start a container
• docker_stop_container - Stop a container
• opnsense_service_restart - Restart OPNsense service

Level 3 - Configure

• docker_read_compose - Read docker-compose.yml
• docker_list_volumes - List Docker volumes
• docker_list_networks - List Docker networks
• docker_inspect_container - Inspect container details
• truenas_list_datasets - List ZFS datasets
• truenas_dataset_info - Get dataset details

Level 4 - Manage

• docker_write_compose - Write docker-compose.yml
• docker_compose_up - Deploy a stack
• docker_compose_down - Remove a stack
• docker_exec - Execute command in container
• truenas_create_snapshot - Create ZFS snapshot

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Type check
npx tsc --noEmit

Security Notes

• The API key should be kept secret and rotated periodically
• Start with the lowest capability level you need
• For Level 4, the /opt/stacks mount must be :rw instead of :ro
• The container requires access to the Docker socket for container management
• OPNsense and TrueNAS APIs use self-signed certificates by default

Troubleshooting

Container won't start

# Check logs
docker compose logs homelab-mcp

# Common issues:
# - Missing API_KEY in .env
# - Invalid CAPABILITY_LEVEL (must be 1-4)
# - Docker socket not accessible

Tools failing

# Test OPNsense API
curl -k -u "key:secret" https://10.0.0.1/api/core/system/status

# Test TrueNAS API
curl -k -H "Authorization: Bearer YOUR_KEY" https://10.0.0.105/api/v2.0/system/info

# Check network connectivity from container
docker exec homelab-mcp ping 10.0.0.1

Permission issues

If you need Level 4 (write access to stacks), update the volume mount:

volumes:
  - /opt/stacks:/opt/stacks:rw  # Change from :ro to :rw

License

MIT

Contributing

Issues and pull requests welcome!