Skip to main content
Glama

Homelab MCP Server

by bshandley
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

Level

Name

Capabilities

1

Monitor

Read-only: container status, logs, stats, system info, service health

2

Operate

Level 1 + start/stop/restart containers and services

3

Configure

Level 2 + read compose files, configs, volumes, networks

4

Manage

Level 3 + write configs, create/remove containers, exec commands

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!

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bshandley/homelab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server