Ansible MCP Server

Homelab MCP 服务

通过模型上下文协议管理 Homelab 基础设施的 AI 驱动方案

一个 Python MCP 服务，可让 AI 助手管理、部署和监控 Homelab 基础设施。工具涵盖 SSH 发现、虚拟机管理、服务安装、网络拓扑映射、Proxmox 操作和凭据管理。

主要功能

• SSH 发现 —— 从任意系统收集全面的硬件和软件信息
• 服务安装 —— 通过模板部署 Jellyfin、Pi-hole、Ollama、Home Assistant 等服务
• Proxmox 集成 —— 提供完整的 API 访问权限，并支持发现社区脚本
• 虚拟机／容器生命周期管理 —— 部署、控制和移除 Docker 与 LXD 工作负载
• 网络映射 —— 发现设备、分析拓扑并跟踪变更
• Terraform 和 Ansible —— 通过状态管理进行部署，支持漂移检测和 Playbook
• 凭据管理 —— 一次注册服务器，连接时无需重复输入凭据

快速开始

# 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 Desktop 设置	Claude Desktop 集成指南
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（创建／更新，即 upsert）、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/

生产部署详情请参阅 DEPLOYMENT.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 社区脚本集成由 community-scripts/ProxmoxVE 提供支持（MIT License）。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 为新功能编写测试
4. 确保所有测试通过
5. 提交 Pull Request

许可证

MIT License —— 详情请参阅 LICENSE 文件。