Homelab MCP
About
MCP servers for managing homelab infrastructure through Claude Desktop. Monitor Docker/Podman containers, Ollama AI models, Pi-hole DNS, Unifi networks, and Ansible inventory.
Details
- Author
- bjeans
- Categories
- Productivity, Infrastructure, Other
Jump to
Setup
Install Homelab MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/bjeans/homelab-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Model Context Protocol (MCP) servers for managing homelab infrastructure through Claude Desktop.
A collection of Model Context Protocol (MCP) servers for managing and monitoring your homelab infrastructure through Claude Desktop.
⚠️ IMPORTANT: Please readSECURITY.mdbefore deploying this project.
This project interacts with critical infrastructure (Docker APIs, DNS, network devices). Improper configuration can expose your homelab to security risks.
- NEVER expose Docker/Podman APIs to the internet- Use firewall rules to restrict access
- Keep.envfile secure- Contains API keys and should never be committed
- Use unique API keys- Generate separate keys for each service
- Review network security- Ensure proper VLAN segmentation and firewall rules
SeeSECURITY.mdfor comprehensive security guidance.
This project includes several documentation files for different audiences:
- README.md(this file) - Installation, setup, and usage guide
- MIGRATION_V3.md- Migration guide for v2.0 unified server
- PROJECT_INSTRUCTIONS.md- Copy into Claude project instructions for AI context
- CLAUDE.md- Developer guide for AI assistants and contributors
- SECURITY.md- Security policies and best practices
- CONTRIBUTING.md- How to contribute to this project
- CHANGELOG.md- Version history and changes
👥 For End Users:Follow this README + copy PROJECT_INSTRUCTIONS.md to Claude🔄 Migrating from v1.x?SeeMIGRATION_V3.mdfor unified server migration🤖 For AI Assistants:ReadCLAUDE.mdfor complete development context🔧 For Contributors:Start with CONTRIBUTING.md andCLAUDE.md
�📖 Important: Configure Claude Project Instructions
After setting up the MCP servers,create your personalized project instructions:
# Windows copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md # Linux/Mac cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
Edit the filewith your actual infrastructure details:
PROJECT_INSTRUCTIONS.md(for Claude Desktop project instructions):
- Replace example IP addresses with your real network addresses
- Add your actual server hostnames
- Customize with your specific services and configurations
- Keep this file private- it contains your network topology
CLAUDE_CUSTOM.md(for AI development work - contributors only):
- Update repository URLs with your actual GitHub repository
- Add your Notion workspace URLs if using task management
- Customize infrastructure references
- Keep this file private- contains your specific URLs and setup
- Open Claude Desktop
- Go to your project settings
- Copy the contents of your customizedPROJECT_INSTRUCTIONS.md
- Paste into the "Project instructions" field
- Detailed MCP server capabilities and usage patterns
- Infrastructure overview and monitoring capabilities
- Specific commands and tools available for each service
- Troubleshooting and development guidance
This README covers installation and basic setup. The project instructions provide Claude with comprehensive usage context.
Version 3.0.0offers flexible deployment with two modes and two methods:
Choose how your MCP servers are organized:
Run all MCP servers in a single process with namespaced tools. This is the recommended approach for new installations andrequired for Docker deployments.
{ "mcpServers": { "homelab-unified": { "command": "python", "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"] } } }
- ✅ Single configuration entry
- ✅ One Python process for all servers
- ✅ Cleaner logs (no duplicate warnings)
- ✅ All tools namespaced (e.g.,docker_get_containers,ping_ping_host)
- ✅ Required for Docker deployments
- ✅ Built-in health checks
- ✅ Production-ready containerization
2. Individual Servers (Legacy, Fully Supported)
Run each MCP server as a separate process. This mode remains fully supported for backward compatibility andonly available with native Python installation.
{ "mcpServers": { "docker": { "command": "python", "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"] }, "ollama": { "command": "python", "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"] } } }
- ✅ Granular control over each server
- ✅ Can enable/disable servers individually
- ✅ Original tool names (e.g.,get_docker_containers,ping_host)
- ✅ Backward compatible with v1.x
Note:Tool names differ between modes. SeeMIGRATION_V3.mdfor detailed migration instructions and tool name changes.
Choose how to install and run the servers:
1. Docker Container (Recommended for Production)
Pre-built images available on Docker Hub for immediate deployment. See🐳 Docker Deploymentfor full setup instructions.
docker pull bjeans/homelab-mcp:latest docker-compose up -d
- ✅ No Python environment setup required
- ✅ Pre-built, tested images
- ✅ Automatic updates with image pulls
- ✅ Multi-platform support (amd64, arm64)
- ✅ Simplified configuration
- ✅ Production-grade containerization
- Unified server mode only
- mcp-registry-inspector not available (deprecated)
2. Native Python Installation (Development & Legacy)
Install Python dependencies directly and run servers from source. See📦 Installationfor full setup instructions.
pip install -r requirements.txt python homelab_unified_mcp.py
- ✅ Full access to source code
- ✅ Easy debugging and development
- ✅ Supports both unified and individual server modes
- ✅ Can run on any Python-compatible platform
- Python 3.10+ with pip
- Manual dependency management
- Environment configuration via .env file
Migration Guide:See[MIGRATION_V3.mdfor detailed instructions on switching between modes or methods.
Version 3.0.0 uses FastMCP:A modern MCP framework that simplifies server architecture while adding support for multiple transport mechanisms and tool annotations.
FastMCP is a lightweight framework that:
- ✅ Reduces server code by 38% (1,754 lines eliminated)
- ✅ Uses simple decorator pattern (@mcp.tool()) for tool definitions
- ✅ Includes comprehensive tool annotations for behavioral hints
- ✅ Adds support for HTTP and SSE transports (in addition to stdio)
- ✅ Auto-generates schemas from Python type hints
- ✅ Improves code maintainability and makes adding new servers easier
All 39 toolsnow include MCP annotations (readOnlyHint,idempotentHint, etc.) to help Claude make informed decisions about tool usage.
FastMCP servers can operate using different transport mechanisms:
1. Standard Input/Output (stdio) - Default
The traditional MCP transport used by Claude Desktop. This is the default and recommended option for most users.
# Run with stdio (default) python homelab_unified_mcp.py # Or explicitly specify stdio transport python homelab_unified_mcp.py --transport stdio
- Claude Desktop integration (default mode)
- Most common use case
- No additional configuration needed
Run MCP servers as HTTP services for remote or flexible deployment scenarios.
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
