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

3. Configuration

Edit .env with your settings:

4. Build and Deploy

5. Configure Claude Desktop

Add to your Claude Desktop MCP settings:

Remote Access (Claude Chat)

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

1. Set environment variables in

   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

   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

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

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

Tools failing

Permission issues

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

License

MIT

Contributing

Issues and pull requests welcome!