JinDaGe - lxd-mcp MCP Details

article

README

🚀 LXD MCP 服务器

这是一个用于管理 LXD 容器和虚拟机的模型上下文协议（MCP）服务器，能为你提供便捷、高效的 LXD 实例管理方案。

🚀 快速开始

前提条件

系统已安装并运行 LXD。
安装 Go 1.25.4 或更高版本。
拥有访问 LXD Unix 套接字的权限（通常要求用户加入 lxd 组）。

安装步骤

构建服务器：

make build

确保二进制文件已添加到系统路径，或记录其完整路径以便后续配置使用。

使用方法

通过 GitHub Copilot CLI 使用

这是使用此 MCP 服务器最简单的方式：

运行以下命令添加服务器：

/mcp add lxd-mcp-server

当系统提示时，提供 lxd-mcp-server 二进制文件的完整路径（例如 /home/user/git/lxd-mcp/lxd-mcp-server）。
服务器将自动完成配置，你可以在 Copilot CLI 会话中开始使用 LXD 工具。
若要验证服务器是否正常运行，可让 Copilot 列出你的 LXD 实例或执行其他 LXD 操作。

直接使用

MCP 服务器还支持通过 JSON - RPC 2.0 协议在标准输入/输出上进行通信：

./lxd-mcp-server

工具调用示例

列出所有实例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_instances",
    "arguments": {}
  }
}

创建一个实例

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_instance",
    "arguments": {
      "name": "my-container",
      "image": "ubuntu:24.04",
      "type": "container",
      "start": true
    }
  }
}

获取实例详细信息

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_instance",
    "arguments": {
      "name": "my-container"
    }
  }
}

更新实例配置

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "update_instance",
    "arguments": {
      "name": "my-container",
      "config": {
        "limits.cpu": "2",
        "limits.memory": "2GiB"
      }
    }
  }
}

启动一个实例

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "start_instance",
    "arguments": {
      "name": "my-container"
    }
  }
}

执行一条命令

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "exec_instance",
    "arguments": {
      "name": "my-container",
      "command": ["ls", "-la", "/"]
    }
  }
}

删除一个实例

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "delete_instance",
    "arguments": {
      "name": "my-container",
      "force": true
    }
  }
}

✨ 主要特性

此 MCP 服务器提供以下工具：

实例管理

list_instances - 列出所有 LXD 实例（容器和虚拟机）。
get_instance - 获取特定实例的详细信息。
get_instance_state - 获取实例的当前状态和资源使用情况。
create_instance - 创建一个新的 LXD 实例（容器或虚拟机）。
delete_instance - 删除一个实例。
rename_instance - 重命名一个实例。
update_instance - 更新实例配置（例如，CPU、内存限制）。

实例生命周期管理

start_instance - 启动一个已停止的实例。
stop_instance - 停止一个正在运行的实例（支持强制停止）。
restart_instance - 重启一个正在运行的实例。
freeze_instance - 冻结（暂停）一个正在运行的实例。
unfreeze_instance - 解冻（恢复）一个已冻结的实例。

实例操作

exec_instance - 在实例中执行命令。

镜像管理

list_images - 列出可用的镜像。

🔧 技术细节

架构

服务器使用 LXD Go 客户端库（github.com/canonical/lxd/client）通过 Unix 套接字 /var/snap/lxd/common/lxd/unix.socket（非 Snap 安装为 /var/lib/lxd/unix.socket）与 LXD 进行交互。

项目结构

lxd-mcp/
├── main.go                          # 应用程序入口点
├── internal/
│   ├── lxd/                         # LXD 工具包
│   │   ├── client.go                # 工具结构体和 LXD 连接
│   │   ├── types.go                 # 参数类型定义
│   │   ├── instances.go             # 实例的创建、读取、更新和删除操作
│   │   ├── lifecycle.go             # 启动/停止/重启操作
│   │   ├── exec.go                  # 命令执行
│   │   └── images.go                # 镜像管理
│   └── server/                      # MCP 服务器设置
│       └── server.go                # 工具注册和服务器初始化
└── doc/                             # 文档资源

🚧 未来增强功能

[ ] 快照管理
[ ] 文件上传/下载操作
[ ] 网络配置
[ ] 存储池管理
[ ] 配置文件管理
[ ] 日志访问
[ ] 镜像导入/导出
[ ] 元数据 API 集成
[ ] 文档端点集成（snap）

⚠️ 安全注意事项

服务器需要 LXD 访问权限（用户必须加入 lxd 组）。
在容器中执行命令存在安全风险。
生产环境使用时，建议实现身份验证机制。
对所有输入参数进行验证。

lxd-mcp