使用说明

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 mcp

2.克隆此仓库

git clone https://github.com/AI-Engineerings-at/homelab-mcp-bundle.git
cd homelab-mcp-bundle

3.配置克劳德桌面

编辑 ~/.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清单。

如果能节省你的时间，请标记此仓库。它帮助其他人找到它。

许可证

麻省理工学院——见许可证

免费使用、修改和分发。赞赏但不要求署名。

使用说明

Homelab MCP捆绑包

目录

概述

建筑

服务

快速安装

1.安装MCP库

2.克隆此仓库

3.配置克劳德桌面

自然语言示例

需求

单个服务器文档

获取完整的Homelab AI堆栈

常见问题解答

贡献

许可证

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务

APISIX MCP服务器