Homelab MCP捆绑包
通过自然语言控制整个家庭实验室。不再切换标签。
______________________________________________________________________
目录
______________________________________________________________________
概述
8台经过生产测试的MCP服务器。40+工具。零外部依赖 mcp.
问克劳德 *“我的服务都结束了吗？”* 并通过一次对话获取Portainer、Uptime Kuma、Proxmox、n8n、AdGuard、Grafana、Ollama和Mattermost的实时状态。
没有云。没有代理。没有数据离开你的网络。每个服务器都是独立的——只使用与你的堆栈匹配的服务器。
______________________________________________________________________
建筑
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每个MCP服务器都作为本地Python进程运行，由Claude Desktop启动和管理。Claude通过发送工具调用 MCP协议 （stdio），每个服务器将它们转换为对自托管服务的直接REST API调用。
______________________________________________________________________
服务
|#|服务器|工具|功能|示例提示| |:-:|--------|:-----:|-------------|----------------| | 1 | 入口MCP |5|列出堆栈、服务、容器；尾原木；检查健康状况| *“显示所有正在运行的Docker Swarm服务”* | | 2 | Proxmox MCP |6|列出VM/LXC、节点状态、资源使用情况、启动/停止/重新启动| *“我的Proxmox节点现在的加载情况如何？”* | | 3 | n8n MCP |5|列出工作流、触发执行、检查失败、管理状态| *“今天哪些n8n工作流失败了？”* | | 4 | Ollama MCP |4|列出模型、拉取/删除模型、生成补全| *“用llama3总结此日志文件”* | | 5 | Kuma MCP正常运行时间 |3|监控状态、正常运行时间百分比、停机检测| *“我的服务都结束了吗？”* | | 6 | Mattermost MCP |5|发布消息、阅读频道、搜索历史、列出团队| *“将‘部署完成’后设置为#general”* | | 7 | AdGuard主页MCP |6|DNS统计、阻止/取消阻止域、查询日志、过滤器管理| *“今天有多少DNS查询被阻止？”* | | 8 | Grafana MCP |6|列出仪表板、检查警报、运行PromQL、添加注释| *“Grafana有开火警报吗？”* |
______________________________________________________________________
快速安装
1.安装MCP库
pip install mcp
# or in a virtual environment:
python3 -m venv .venv && source .venv/bin/activate && pip install mcp2.克隆此仓库
git clone https://github.com/AI-Engineerings-at/homelab-mcp-bundle.git
cd homelab-mcp-bundle3.配置克劳德桌面
编辑 ~/.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"
}
}
}
}重新启动Claude Desktop——服务器会自动显示为工具。
______________________________________________________________________
自然语言示例
"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______________________________________________________________________
需求
- 克劳德桌面版 （启用MCP支持）
- Python 3.9+ 和
pip install mcp（唯一的库依赖项） - 自托管服务 您要连接：
- Portainer CE或BE（Docker Swarm或独立） - Proxmox VE（任何最新版本） - n8n（自托管，启用API密钥） - Ollama（本地LLM运行时） - Kuma正常运行时间（已配置状态页） - Mattermost（自托管，机器人代币） - AdGuard主页 - 格拉法娜+普罗米修斯
您不需要所有这些——每个服务器都是完全独立的。
______________________________________________________________________
单个服务器文档
______________________________________________________________________
获取完整的Homelab AI堆栈
此捆绑包是 Playbook 01 - 本地人工智能堆栈，使用Docker Swarm、n8n自动化、Grafana监控和Claude Desktop集成构建生产级自托管AI基础设施的完整指南。
在ai-enengineering.at上获取Playbook 01
包括：
- 完成Docker Swarm设置（Portainer、Grafana、Prometheus、n8n、Ollama）
- 13准备导入n8n AI自动化工作流程
- 22个用于家庭实验室监控的Grafana仪表板
- 具有本地LLM分析的AIOps警报管道
- 分步设置指南（70页，德语/英语）
______________________________________________________________________
常见问题解答
Do I need a cloud LLM or a paid API?
不需要云。此捆绑包中的每台服务器都会直接对您的自托管服务进行HTTP调用，任何东西都不会离开您的网络 ollama-mcp 服务器连接到在您自己的硬件上运行的本地Ollama实例。您可以完全脱机运行整个堆栈。唯一的“云”组件是Claude Desktop本身，它在您的机器上本地运行MCP服务器。
What version of Claude Desktop is required?
支持MCP（模型上下文协议）的任何版本的Claude Desktop。MCP支持于2024年底推出。如果您的Claude桌面显示“工具”部分并允许您进行配置 mcpServers 在配置文件中，它将工作。检查 模型上下文协议.io 获取最新的兼容性信息。
Can I use these servers without having all 8 services running?
对。每个MCP服务器都是完全独立的。您可以使用一个、三个或全部八个——Claude Desktop只启动您配置的服务器。如果你只运行Proxmox和Grafana，只需将这两个添加到你的 claude_desktop_config.json 忽略其余部分。服务器之间没有共享依赖关系。
How do I update the servers after pulling new changes?
cd homelab-mcp-bundle
git pull然后重新启动Claude Desktop。服务器是普通的Python脚本，不需要编译或重建。Claude Desktop在每次启动时都会为每台服务器启动一个新进程，因此新代码在重新启动后立即生效。
Can I use these MCP servers with Claude.ai in the browser?
不是。MCP是一种本地协议，在Claude Desktop（本机应用程序）和您计算机上的本地服务器进程之间运行。它在Claude.ai web界面中不可用。您需要在计算机上安装Claude Desktop应用程序才能使用MCP服务器。
My service is not in this bundle. How do I build a custom MCP server?
看 贡献.md 以获得一个完整的分步指南和一个工作框架。简短版本：
- 创建一个新目录
your-service-mcp/ - 从以下位置复制结构
portainer-mcp/作为起始模板 - 用服务的REST API替换API调用
- 添加装饰您的工具功能
@mcp.tool() - 将其添加到您的Claude Desktop配置中
任何带有REST API的服务都可以通过这种方式封装在MCP服务器中。对于一个简单的服务，整个过程通常需要不到一个小时。
Does this work on Windows?
是的，通过两种方法：
- WSL2（推荐）：在Linux的Windows子系统中运行Python服务器。Windows上的Claude Desktop配置使用WSL路径格式：
wsl.exe python3 /home/user/homelab-mcp-bundle/portainer-mcp/server.py这是最可靠的方法。 - Windows上的原生Python：从Python.org安装Python 3.9+，运行
pip install mcp，并在配置中使用Windows样式的路径。所有服务器仅使用标准库+mcp，因此没有仅依赖Linux的依赖关系。
______________________________________________________________________
贡献
欢迎发布问题和PR。如果您为自托管服务添加新的MCP服务器，请打开PR！
看 贡献.md 完整指南：如何添加服务器、代码风格、测试和PR清单。
如果能节省你的时间，请标记此仓库。它帮助其他人找到它。
______________________________________________________________________
许可证
麻省理工学院——见 许可证
免费使用、修改和分发。赞赏但不要求署名。