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, TrueNAS storage, Proxmox virtualization, and Home Assistant service status.

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
• Proxmox Integration: Monitor and manage VMs/containers, create snapshots
• Home Assistant Integration: Monitor service health, entity states, configuration, and error logs
• System Monitoring: CPU, memory, disk usage on the host

⚠️ DANGER - READ THIS FIRST

This software grants AI models direct control over your network infrastructure. Use with extreme caution.

Critical Risks

• AI Can Make Mistakes: Language models can misinterpret instructions, hallucinate requirements, or execute unintended actions. A simple request like "clean up unused containers" could result in critical services being stopped.

• Destructive Actions Are Possible: At higher capability levels (3-4), the AI can:

  • Delete virtual machines and containers
  • Modify network configurations
  • Remove critical datasets or snapshots
  • Execute arbitrary commands in production systems
  • Overwrite docker-compose files, potentially causing data loss

• No Undo Button: Once the AI executes a destructive action (deletes a VM, removes a dataset, stops a critical service), the damage is immediate and may be irreversible.

• Network Security Implications: This server provides API access to your firewall, storage system, and virtualization platform. A compromised API key or misconfigured capability level could allow unauthorized control over your entire homelab.

• Misunderstandings Happen: AI models may not fully understand your infrastructure's dependencies. Restarting one service could cascade into network-wide outages.

Recommendations

1. Start with Level 1 (Read-Only): Always begin with monitoring-only access and only increase capability levels when absolutely necessary.

2. Test in Development: If possible, test with non-production infrastructure first to understand how the AI interprets your requests.

3. Review Before Executing: At Level 2+, carefully review what actions the AI plans to take before confirming execution.

4. Keep Backups: Ensure you have recent backups of all critical systems before granting Level 3+ access.

5. Rotate Credentials: Regularly rotate API keys and OAuth credentials. Treat them as highly sensitive.

6. Monitor Logs: Watch the container logs to see what actions are being executed in real-time.

7. Use Network Segmentation: Consider running this server in a restricted network segment with limited access to critical infrastructure.

BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU UNDERSTAND THESE RISKS AND ACCEPT FULL RESPONSIBILITY FOR ANY ACTIONS TAKEN BY THE AI, INCLUDING DATA LOSS, SERVICE DISRUPTION, OR SECURITY INCIDENTS.

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

# Proxmox (optional)
PROXMOX_HOST=10.0.0.2
PROXMOX_TOKEN_ID=root@pam!mytoken
PROXMOX_TOKEN_SECRET=your-secret

# Home Assistant (optional)
HOME_ASSISTANT_HOST=10.0.0.103
HOME_ASSISTANT_PORT=8123
HOME_ASSISTANT_TOKEN=your-long-lived-token
HOME_ASSISTANT_USE_HTTPS=false

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",
        "PROXMOX_HOST": "10.0.0.2",
        "PROXMOX_TOKEN_ID": "root@pam!mytoken",
        "PROXMOX_TOKEN_SECRET": "your-secret",
        "HOME_ASSISTANT_HOST": "10.0.0.103",
        "HOME_ASSISTANT_PORT": "8123",
        "HOME_ASSISTANT_TOKEN": "your-long-lived-token",
        "HOME_ASSISTANT_USE_HTTPS": "false"
      }
    }
  }
}

Remote Access (Claude Chat)

For accessing the MCP server from Claude Chat (web interface), deploy with HTTP transport:

1. Set environment variables in .env:

   PORT=3000
   API_KEY=your-generated-key
   CAPABILITY_LEVEL=1
   

2. Deploy the container:

   docker compose up -d
   

3. Configure reverse proxy (e.g., Traefik, Pangolin, nginx) to route mcp.example.com to http://localhost:3000

4. Add DNS record pointing mcp.example.com to your server

5. In Claude Chat, add the MCP server:

   • URL: https://mcp.example.com/mcp
   • Authentication: Bearer token
   • Token: Your API_KEY value

OAuth 2.0 Authentication (for Claude Chat)

Claude Chat requires OAuth 2.0 for custom connectors. This server supports the Client Credentials flow.

1. Generate OAuth credentials:

   # Generate client ID
   openssl rand -hex 32
   
   # Generate client secret
   openssl rand -hex 32
   

2. Add to .env:

   OAUTH_CLIENT_ID=your-generated-client-id
   OAUTH_CLIENT_SECRET=your-generated-client-secret
   

3. In Claude Chat, add the connector:

   • Name: Homelab
   • Remote MCP server URL: https://mcp.example.com/mcp
   • OAuth Client ID: Your generated client ID
   • OAuth Client Secret: Your generated client secret

The server will issue access tokens valid for 1 hour. Claude Chat handles token refresh automatically.

Endpoints

When running in HTTP mode:

Testing

# Test health endpoint
curl https://mcp.example.com/health

# Get an access token
curl -X POST https://mcp.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# Use the token
curl https://mcp.example.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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
• proxmox_status - Get Proxmox cluster status
• proxmox_list_vms - List all VMs and containers
• proxmox_vm_status - Get VM/container status
• home_assistant_status - Get Home Assistant version and entity counts
• home_assistant_list_entities - List all entities (lights, switches, sensors)
• home_assistant_get_entity - Get specific entity state and attributes

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
• proxmox_start_vm - Start a VM/container
• proxmox_stop_vm - Stop a VM/container
• proxmox_shutdown_vm - Gracefully shutdown a VM/container
• proxmox_reboot_vm - Reboot a VM/container

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
• proxmox_vm_config - Get VM/container configuration
• proxmox_list_storage - List Proxmox storage
• proxmox_list_nodes - List cluster nodes
• home_assistant_get_config - Get Home Assistant configuration
• home_assistant_error_log - Get error log

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
• proxmox_create_snapshot - Create VM/container snapshot
• proxmox_delete_vm - Delete a VM/container

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

# Test Home Assistant API
curl -H "Authorization: Bearer YOUR_TOKEN" http://10.0.0.103:8123/api/

# 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!