Homelab MCP Bundle
Control your entire homelab through natural language. No more switching tabs.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
8 production-tested MCP servers. 40+ tools. Zero external dependencies beyond mcp.
Ask Claude "Are all my services up?" and get a live status across Portainer, Uptime Kuma, Proxmox, n8n, AdGuard, Grafana, Ollama, and Mattermost — all from one conversation.
No cloud. No proxy. No data leaves your network. Each server is independent — use only the ones that match your stack.
graph LR
CD["Claude Desktop"]
CD -->|stdio / MCP| MM["Mattermost MCP"]
CD -->|stdio / MCP| N8["n8n MCP"]
CD -->|stdio / MCP| PX["Proxmox MCP"]
CD -->|stdio / MCP| UK["Uptime Kuma MCP"]
CD -->|stdio / MCP| OL["Ollama MCP"]
CD -->|stdio / MCP| PT["Portainer MCP"]
CD -->|stdio / MCP| AG["AdGuard MCP"]
CD -->|stdio / MCP| GR["Grafana MCP"]
MM -->|REST API| MM_S["Mattermost"]
N8 -->|REST API| N8_S["n8n"]
PX -->|REST API| PX_S["Proxmox VE"]
UK -->|REST API| UK_S["Uptime Kuma"]
OL -->|REST API| OL_S["Ollama"]
PT -->|REST API| PT_S["Portainer"]
AG -->|REST API| AG_S["AdGuard Home"]
GR -->|REST API| GR_S["Grafana"]
style CD fill:#6366f1,stroke:#4f46e5,color:#fff
style MM fill:#1e88e5,stroke:#1565c0,color:#fff
style N8 fill:#ff6d00,stroke:#e65100,color:#fff
style PX fill:#e6a117,stroke:#c68a00,color:#fff
style UK fill:#5cdd8b,stroke:#34b36a,color:#fff
style OL fill:#333,stroke:#555,color:#fff
style PT fill:#13bef9,stroke:#0d9fd8,color:#fff
style AG fill:#68bc71,stroke:#4a9d52,color:#fff
style GR fill:#f46800,stroke:#cc5700,color:#fff
Each MCP server runs as a local Python process started and managed by Claude Desktop. Claude sends tool calls via the MCP protocol (stdio), and each server translates them into direct REST API calls to your self-hosted service.
pip install mcp
# or in a virtual environment:
python3 -m venv .venv && source .venv/bin/activate && pip install mcp
git clone https://github.com/AI-Engineerings-at/homelab-mcp-bundle.git
cd homelab-mcp-bundle
Edit ~/.config/claude/claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)
{
"mcpServers": {
"portainer": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/portainer-mcp/server.py"],
"env": {
"PORTAINER_URL": "http://your-portainer:9000",
"PORTAINER_USER": "admin",
"PORTAINER_PASSWORD": "your-password"
}
},
"proxmox": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/proxmox-mcp/server.py"],
"env": {
"PVE_HOST": "your-proxmox-ip",
"PVE_USER": "root@pam",
"PVE_PASSWORD": "your-password"
}
},
"n8n": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/n8n-mcp/server.py"],
"env": {
"N8N_API_KEY": "your-n8n-api-key",
"N8N_BASE_URL": "http://your-n8n:5678/api/v1"
}
},
"ollama": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/ollama-mcp/server.py"],
"env": {
"OLLAMA_BASE_URL": "http://localhost:11434",
"OLLAMA_DEFAULT_MODEL": "llama3.2:3b"
}
},
"uptime-kuma": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/uptime-kuma-mcp/server.py"],
"env": {
"KUMA_BASE_URL": "http://your-uptime-kuma:3001",
"KUMA_STATUS_PAGE": "homelab"
}
},
"mattermost": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/mattermost-mcp/server.py"],
"env": {
"MM_TOKEN": "your-mattermost-bot-token",
"MM_BASE_URL": "http://your-mattermost:8065/api/v4"
}
},
"adguard": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/adguard-mcp/server.py"],
"env": {
"ADGUARD_URL": "http://your-adguard:3000",
"ADGUARD_USER": "admin",
"ADGUARD_PASSWORD": "your-password"
}
},
"grafana": {
"command": "python3",
"args": ["/path/to/homelab-mcp-bundle/grafana-mcp/server.py"],
"env": {
"GRAFANA_URL": "http://your-grafana:3000",
"GRAFANA_API_KEY": "your-grafana-api-key"
}
}
}
}
Restart Claude Desktop — the servers appear as tools automatically.
"Show me all VMs on my Proxmox cluster"
-> proxmox-mcp: vms_list() -> 12 VMs/LXCs across 3 nodes
"Are all my services up?"
-> uptime-kuma-mcp: monitors_status() -> 28/28 UP
"Which n8n workflows failed today?"
-> n8n-mcp: executions_list(status="error") -> 2 failed
"Write to #general: Deployment is done"
-> mattermost-mcp: posts_create(channel="general", ...) -> Posted
"Summarize this error log with llama3"
-> ollama-mcp: generate(prompt="...", model="llama3.2:3b") -> Summary
"Show me all running Docker Swarm services"
-> portainer-mcp: services_list() -> 22 services across 3 nodes
"How many DNS queries were blocked today?"
-> adguard-mcp: stats() -> 45,230 queries | 12,847 blocked (28.4%)
"Block ads.example.com"
-> adguard-mcp: block_domain("ads.example.com") -> Rule added
"Show current Grafana alerts"
-> grafana-mcp: alerts_list() -> 1 firing: HighMemory on node-1
pip install mcp (the only library dependency)You don't need all of them — each server is fully independent.
This bundle is part of Playbook 01 — Der Lokale AI-Stack, a complete guide to building a production-grade, self-hosted AI infrastructure with Docker Swarm, n8n automation, Grafana monitoring, and Claude Desktop integration.
Includes:
No cloud required. Every server in this bundle makes direct HTTP calls to your self-hosted services — nothing ever leaves your network. The ollama-mcp server connects to a local Ollama instance running on your own hardware. You can run the entire stack completely offline. The only "cloud" component is Claude Desktop itself, which runs the MCP servers locally on your machine.
Any version of Claude Desktop that supports MCP (Model Context Protocol). MCP support was introduced in late 2024. If your Claude Desktop shows a "Tools" section and allows you to configure mcpServers in the config file, it will work. Check modelcontextprotocol.io for the latest compatibility information.
Yes. Each MCP server is completely independent. You can use one, three, or all eight — Claude Desktop only starts the servers you configure. If you only run Proxmox and Grafana, just add those two to your claude_desktop_config.json and ignore the rest. There are no shared dependencies between servers.
cd homelab-mcp-bundle
git pull
Then restart Claude Desktop. The servers are plain Python scripts — there is nothing to compile or rebuild. Claude Desktop starts a fresh process for each server on every launch, so the new code takes effect immediately after restart.
No. MCP is a local protocol that runs between Claude Desktop (the native app) and local server processes on your machine. It is not available in the Claude.ai web interface. You need the Claude Desktop app installed on your computer to use MCP servers.
See the CONTRIBUTING.md for a complete step-by-step guide with a working skeleton. The short version:
your-service-mcp/portainer-mcp/ as a starting template@mcp.tool()Any service with a REST API can be wrapped in an MCP server this way. The whole thing typically takes under an hour for a simple service.
Yes, via two approaches:
wsl.exe python3 /home/user/homelab-mcp-bundle/portainer-mcp/server.py. This is the most reliable approach.pip install mcp, and use Windows-style paths in your config. All servers use only the standard library plus mcp, so there are no Linux-only dependencies.Issues and PRs welcome. If you add a new MCP server for a self-hosted service, open a PR!
See CONTRIBUTING.md for the full guide: how to add a server, code style, testing, and the PR checklist.
Star this repo if it saved you time. It helps others find it.
MIT — see LICENSE
Free to use, modify, and distribute. Attribution appreciated but not required.
8 MCP servers for self-hosted homelab infrastructure. Docker, Proxmox, n8n, monitoring, secrets.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Homelab MCP Bundle 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 8 MCP servers for self-hosted homelab infrastructure. Docker, Proxmox, n8n, monitoring, secrets.