AI导哈

AI基础设施管理服务器

一个基于Python的MCP服务器，通过AI助手管理、部署和监控家庭实验室基础设施，包括SSH发现、虚拟机管理、服务安装、网络拓扑映射等功能。

  • by washyu
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 washyu/mcp_python_server

使用说明

Homelab MCP服务器

通过模型上下文协议进行人工智能驱动的家庭实验室基础设施管理

Python MCP服务器，使AI助手能够管理、部署和监控家庭实验室基础设施。工具涵盖SSH发现、VM管理、服务安装、网络拓扑映射、Proxmox操作和凭据管理。

主要特点

  • SSH发现 --从任何系统收集全面的硬件和软件信息
  • 服务安装 --从模板中部署Jellyfin、Pi hole、Ollama、Home Assistant等
  • Proxmox集成 --API完全访问加上社区脚本发现
  • VM/容器生命周期 --部署、控制和删除Docker和LXD工作负载
  • 网络映射 --发现设备、分析拓扑结构并跟踪更改
  • Terraform和Ansible --具有漂移检测和剧本的状态管理部署
  • 凭据管理 --注册服务器一次，无需重新输入凭据即可连接

快速开始

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

有关完整的演练（环境变量、MCP客户端配置、第一次工具调用），请参阅 安装指南.

文档

指南 说明
安装指南 从零到第一次工具调用
工具参考 所有带有论据和示例的工具
配置 环境变量和CLI选项
Claude桌面设置 Claude桌面集成指南
HTTP服务 REST/OpenAPI模式、端点和错误契约

运作原理

  1. 设置 --服务器在首次运行时生成SSH密钥对(~/.ssh/mcp_admin_rsa)
  2. 登上主机 --使用 setup_mcp_admin 在目标系统上创建托管用户
  3. 验证 --使用 verify_mcp_admin 确认无密码SSH访问
  4. 管理 --发现硬件、安装服务、控制虚拟机并映射网络

服务器使用MCP协议通过stdio进行通信。将其连接到任何兼容MCP的客户端（Claude Desktop等），并通过自然语言进行交互。

凭据管理

将SSH和Proxmox凭据存储一次，以便服务器在每个连接上自动注入它们：

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

CLI提供完整的CRUD凭据： add （创建/更新-追加销售）， list （阅读）， remove （删除）。没有单独的 update 子命令--重新运行 add 替换密钥环密钥和注册表项的身份验证类型。

凭据存储在操作系统密钥环中（Linux上的libsecret，macOS上的Keychain）。当操作系统密钥环不可用（无头服务器）时，凭据会回退到环境变量。

看 凭据CLI参考 获取完整文档。

MCP客户端配置

来自PyPI（uvx）——推荐：

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-mcp"]
    }
  }
}

从源克隆：

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

发展

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

看 部署.md 有关生产部署的详细信息。

项目结构

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

致谢

Proxmox社区脚本集成由 社区脚本/ProxmoxVE （MIT许可证）。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 为新功能编写测试
  4. 确保所有测试通过
  5. 提交拉取请求

许可证

MIT许可证——有关详细信息，请参阅许可证文件。

相关 MCP