Homelab MCP Server

How to use

You interact with the MCP server through an MCP client. Start with Level 1 to monitor read-only data such as container status, service health, and host metrics. If you need to take action, move up to higher capability levels and perform tasks like starting or stopping containers, restarting services, or inspecting configurations. Regularly review the planned actions before proceeding, especially at higher levels.

How to install

# Prerequisites
- Docker and Docker Compose installed on the target host
- Node.js 20+ (for local development)
- Optional: OPNsense TrueNAS Proxmox Home Assistant credentials

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

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

# 3. Generate a secure API key
openssl rand -hex 32

# 4. Edit the environment file and add credentials
nano .env

Configuration and ongoing operation

Configure the MCP server settings in your environment file. Set the desired capability level, API key, port, and any optional service credentials you use (OPNsense, TrueNAS, Proxmox, Home Assistant). The server exposes an HTTP interface for remote clients as well as a local JavaScript runtime entry point if you want to run it directly inside a Node.js environment.

env
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

Running and testing locally

Build and start the server, then verify basic health and endpoints. You can run the server in a container or as a local Node.js process depending on your environment.

# Build TypeScript and compose images
npm install
npm run build

docker compose build

docker compose up -d

# Check logs
docker compose logs -f

Claude Desktop and remote access

You can connect Claude Desktop to the MCP server using either a remote HTTP endpoint or a local runtime config. The HTTP endpoint is the preferred remote option, while the local stdio option lets you run the server directly on your machine.

# HTTP remote config example
{
  "mcpServers": {
    "homelab": {
      "type": "http",
      "name": "homelab_mcp",
      "url": "https://mcp.example.com/mcp",
      "args": []
    }
  }
}

OAuth 2.0 authentication (for Claude Chat)

If you use OAuth 2.0 for Claude Chat, generate client credentials and add them to your environment or the client settings so the connector can obtain access tokens automatically.

# Generate OAuth credentials
openssl rand -hex 32
openssl rand -hex 32

End-to-end endpoints and testing

The server exposes health and MCP endpoints to support health checks and protocol requests. You can test health and token endpoints, then perform routine MCP calls to list, inspect, or manage resources.

curl https://mcp.example.com/health

Security considerations

Start with read-only access and only elevate permissions when necessary. Rotate API keys regularly, monitor logs in real time, and isolate the MCP server in a restricted network segment with limited access to critical systems.

Troubleshooting

Common issues include missing API keys, incorrect capability levels, or Docker socket access problems. Review container logs to identify failures and verify that all optional service credentials are reachable.

Notes on capabilities and safety

Be aware that higher capability levels grant broader control over your infrastructure, including the ability to modify configurations or stop services. Always exercise caution and verify planned actions before execution.

Appendix: Quick configuration references

# Complete env reference used by the local runtime example
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
PORT=3005

Security notes

The API key should be kept secret and rotated periodically. Start with the lowest capability level you need, and for Level 4 ensure the stacks directory is mounted read-write as required. The MCP server requires access to the Docker socket for container management and may use self-signed certificates for OPNsense and TrueNAS connections.

docker_list_containers

List all Docker containers and their basic status

docker_container_logs

Fetch logs for a specific container

docker_container_stats

Return CPU/memory statistics for containers

system_info

Provide host system information such as CPU, memory, and disk usage

opnsense_status

Retrieve current OPNsense firewall status

truenas_status

Check TrueNAS pool health and status

truenas_alerts

Fetch TrueNAS alerts and events

proxmox_status

Get Proxmox cluster status

proxmox_list_vms

List all VMs and containers managed by Proxmox

proxmox_vm_status

Get status for a specific VM/container

home_assistant_status

Get Home Assistant version and entity counts

home_assistant_list_entities

List all Home Assistant entities

home_assistant_get_entity

Get a specific Home Assistant entity state and attributes

docker_restart_container

Restart a Docker container

docker_start_container

Start a Docker container

docker_stop_container

Stop a Docker container

opnsense_service_restart

Restart an OPNsense service

proxmox_start_vm

Start a Proxmox VM/container

proxmox_stop_vm

Stop a Proxmox VM/container

proxmox_shutdown_vm

Gracefully shutdown a Proxmox VM/container

proxmox_reboot_vm

Reboot a Proxmox VM/container

docker_read_compose

Read a docker-compose.yml file

docker_list_volumes

List Docker volumes

docker_list_networks

List Docker networks

docker_inspect_container

Inspect container details

truenas_list_datasets

List TrueNAS datasets

truenas_dataset_info

Get details about a TrueNAS dataset

proxmox_vm_config

Get VM/container configuration from Proxmox

proxmox_list_storage

List Proxmox storage

proxmox_list_nodes

List Proxmox cluster nodes

home_assistant_get_config

Get Home Assistant configuration

home_assistant_error_log

Retrieve Home Assistant error logs

docker_write_compose

Write or modify a docker-compose.yml file

docker_compose_up

Deploy a docker-compose stack

docker_compose_down

Remove a docker-compose stack

docker_exec

Execute a command inside a running container

truenas_create_snapshot

Create a ZFS snapshot in TrueNAS

proxmox_create_snapshot

Create a VM/container snapshot in Proxmox

proxmox_delete_vm

Delete a VM/container in Proxmox