homelab-mcp-server

MCP server exposing homelab gateway capabilities as AI tools for the Homelab AI Platform.

Part of the homelab-ai platform.

Overview

This server implements the Model Context Protocol (MCP) and exposes tools that an AI assistant uses to manage Minecraft servers and other containerized workloads in a HashiCorp Nomad cluster. It aggregates capabilities from 6 gateway services into a unified, AI-friendly tool surface.

Key capabilities:

• 40+ MCP tools across 3 layers (atomic, orchestration, high-level)
• Modpack Knowledge Base — persistent deployment knowledge for Minecraft modpacks (RAM, JVM args, mod intelligence, config overrides)
• Discovery Pipeline — 7-stage async pipeline that auto-populates KB entries for unknown modpacks (resolve, download, extract, analyze, API enrich, web search, finalize)
• Multi-platform modpack support — CurseForge, Modrinth, and FTB API clients
• Web search enrichment — uses Anthropic API with web search to find deployment guides, known issues, and server tuning recommendations

Quick Start

cp .env.example .env
# Fill in required values
go run ./cmd/server

Build, Test, Run

Go is installed at ~/bin/go/bin/go (also on $PATH via .bashrc).

make build    # Build binary
make test     # Run tests
make lint     # Run linter
make cover    # Coverage report
make run      # Run server
make hooks    # Install pre-commit hook
make clean    # Remove build artifacts

Architecture

The MCP server runs as a subprocess of the chatbot, communicating via stdio transport. It delegates all infrastructure operations to gateway HTTP APIs:

chatbot (subprocess) → homelab-mcp-server (stdio) → gateway HTTP APIs

Tool Layers

Configuration

All config via ENV vars. See .env.example for the full list.

Docker

docker build -t homelab-mcp-server .
docker build --build-arg VERSION=v1.0.0 -t homelab-mcp-server .

License

Private — part of the homelab-ai platform.