🖥️ VirtualBox MCP服务器

![TypeScript](https://www.typescriptlang.org/) ![MCP SDK](https://modelcontextprotocol.io/) ](https://www.npmjs.com/package/@use.manus.ai/virtualbox-mcp-server) ![License: MIT](LICENSE) ![Turborepo](https://turbo.build/)

一个强大的模型上下文协议（MCP）服务器，用于通过Vagrant管理VirtualBox VM。

AI代理现在可以提供、管理和调试具有完全可观察性的虚拟开发环境。

特性 • 快速开始 • 工具 • 工作流 • 例子 • 配置

______________________________________________________________________

✨ 特性

38 MCP工具 用于完整的VM生命周期管理
实时可观测性 具有日志、仪表板和进度跟踪功能
快照管理 用于安全回滚和恢复
过程控制 具有kill/list功能
文件同步 解决冲突
异步操作 具有进度跟踪和取消功能
系统护栏 用于僵尸VM检测和清理
顺序思维 用于解决人工智能问题

______________________________________________________________________

📦 建筑

Virtualbox-mcp-server/          # Turborepo Monorepo
├── apps/
│   └── mcp-server/             # Main MCP server (38 tools)
│       └── src/
│           ├── index.ts        # Tool definitions & handlers
│           ├── error-handler.ts
│           ├── port-manager.ts
│           └── sequential-thinking.ts
├── packages/
│   ├── vagrant-client/         # Vagrant CLI wrapper
│   ├── sync-engine/            # Chokidar + file sync
│   └── shared-utils/           # Logger utilities
├── turbo.json
└── package.json

VirtualBox MCP Architecture Overview

VirtualBox MCP Architecture Detail

______________________________________________________________________

🚀 快速开始

先决条件

Node.js 18+
VirtualBox 6.x或7.x
流浪者 2.3+

安装

# Install via NPM (Recommended)
npm install -g @use.manus.ai/virtualbox-mcp-server

# Or Clone and Build from Source
git clone https://github.com/usemanusai/Virtualbox-mcp-server.git
cd Virtualbox-mcp-server

# Install dependencies
npm install

# Build all packages
npm run build

运行服务器

# Run the installed server
virtualbox-mcp-server

# Or run from source
node apps/mcp-server/dist/index.js

______________________________________________________________________

🛠️ 全部38个工具

VM生命周期（6个工具）

工具	说明
`create_vm`	创建新的Vagrant虚拟机
`create_dev_vm`	创建具有完整配置（CPU、内存、端口、同步）的VM
`ensure_dev_vm`	启动或创建VM（如果不存在）
`get_vm_status`	获取VM状态
`list_vms`	列出所有虚拟机
`destroy_vm`	销毁虚拟机（强制）

执行（3个工具）

工具	说明
`exec_command`	在VM中执行命令（超时）
`exec_with_sync`	在之前/之后使用rsync执行
`run_background_task`	运行nohup后台任务

环境设置（3个工具）

工具	说明
`setup_dev_environment`	安装运行时（node、python、go等）
`install_dev_tools`	安装工具（git、docker、nginx等）
`configure_shell`	配置别名和环境变量

文件操作（7个工具）

工具	说明
`upload_file`	将文件上传到VM
`search_files`	在VM中搜索
`configure_sync`	配置文件监视器
`sync_to_vm`	Rsync主机→VM
`sync_from_vm`	Rsync虚拟机→主持人
`sync_status`	获取同步状态
`resolve_conflict`	解决同步冲突

👁️ 可观察性（3个工具）

工具	说明
`tail_vm_log`	读取日志文件的最后N行（例如。， `/var/log/syslog`)
`get_task_output`	获取后台任务的stdout/stderr
`grep_log_stream`	在日志文件中搜索模式

📸 快照（4个工具）

工具	说明
`snapshot_save`	在风险操作之前创建命名快照
`snapshot_restore`	还原到特定快照
`snapshot_list`	列出所有可用快照
`snapshot_delete`	删除特定快照

⚙️ 过程控制（2个工具）

工具	说明
`list_processes`	返回正在运行的进程的结构化列表(`ps aux`)
`kill_process`	向进程发送SIGTERM/SIGKILL

🌐 网络（1个工具）

工具	说明
`check_vm_port`	验证端口是否正在VM中侦听并且可以从主机访问

📊 仪表板（1个工具）

工具	说明
`get_vm_dashboard`	综合仪表板：CPU、RAM、磁盘、任务、日志

⏳ 进步意识（5个工具）

工具	说明
`start_download`	开始跟踪下载，返回operation_id
`get_operation_progress`	获取实时进度（字节、%、预计到达时间）
`wait_for_operation`	阻塞，直到操作完成或超时
`cancel_operation`	取消正在运行的操作
`list_active_operations`	列出所有活动操作

🛡️ 护栏和维护（2个工具）

工具	说明
`scan_system_health`	检查磁盘/内存，识别僵尸虚拟机
`cleanup_zombies`	安全销毁孤立的虚拟机（带模拟运行选项）

🧠 人工智能推理（1个工具）

工具	说明
`sequentialthinking`	通过反射和分支动态解决问题

______________________________________________________________________

🔄 建筑工作流

🟢 简单的工作流程

1.“每日站立”（环境准备）

快速将开发环境上线并确保其准备就绪：

工作流程： ensure_dev_vm → sync_to_vm → install_dev_tools → get_vm_dashboard

ensure_dev_vm --自动启动或创建虚拟机
sync_to_vm --将本地代码更改推送到VM
install_dev_tools --验证工具是否存在
get_vm_dashboard --确认VM是否正常

2.“数据集提取”（异步下载）

下载大文件而不阻塞：

工作流程： start_download → wait_for_operation → search_files

start_download --启动下载，获取 operation_id
wait_for_operation --阻止，直到下载完成
search_files --验证文件是否存在于预期路径

3.“服务脉冲”（基本调试）

快速诊断原因 localhost:8080 未加载：

工作流程： list_vms → check_vm_port → tail_vm_log

list_vms --确定哪个VM处理该服务
check_vm_port --检查应用程序是否正在侦听（与端口转发问题相比）
tail_vm_log --提取错误日志的最后50行

______________________________________________________________________

🔴 高级工作流

4.“安全第一”更新（事务性回滚）

使用安全网应用有风险的更新：

工作流程： snapshot_save → start_download → check_vm_port → （回滚或删除快照）

snapshot_save --创建检查点“pre-update-v2”
start_download --下载新的二进制文件/补丁
wait_for_operation --阻止直到完成
exec_command --运行安装脚本
check_vm_port --验证服务是否已重新联机

- 如果失败： snapshot_restore 回滚 - 如果成功： snapshot_delete 清理

5.“资源回收”（系统卫生）

识别并清理孤立的僵尸虚拟机：

工作流程： scan_system_health → sequentialthinking → cleanup_zombies → get_vm_dashboard

scan_system_health --识别消耗资源的僵尸虚拟机
sequentialthinking --分析哪些可以安全删除
cleanup_zombies --安全终止 dry_run 第一
get_vm_dashboard --确认资源已释放

6.“深度修复”循环（智能调试）

卡住流程的自主诊断和修复：

工作流程： get_vm_dashboard → list_processes → grep_log_stream → sequentialthinking → kill_process → exec_with_sync

get_vm_dashboard --检测CPU峰值或卡住的任务
list_processes --查找导致问题的特定PID
grep_log_stream --在日志中搜索错误签名
sequentialthinking --提出假设
kill_process --将SIGTERM发送到卡住的进程
exec_with_sync --上传已修补的配置并重新启动

______________________________________________________________________

💬 示例提示

以下是30个自然语言提示及其相应的工具调用：

VM Lifecycle Examples

1.提供新的数据库服务器

“我需要一个新的Redis服务器。使用‘hashicorp/bionic64’框创建一个名为‘Redis-cache’的VM。”

{
  "name": "create_vm",
  "arguments": {
    "name": "redis-cache",
    "box": "hashicorp/bionic64"
  }
}

2.状态检查

“‘前端反应’虚拟机当前是否正在运行？”

{
  "name": "get_vm_status",
  "arguments": {
    "name": "frontend-react"
  }
}

3.库存概况

“显示我们当前管理的所有虚拟机的列表。”

{
  "name": "list_vms",
  "arguments": {}
}

4.强制终止

“‘experiment-01’虚拟机完全没有响应。请立即销毁它。”

{
  "name": "destroy_vm",
  "arguments": {
    "name": "experiment-01"
  }
}

5.临时环境检查

确保“集成测试”虚拟机正在运行。如果没有，请创建它

{
  "name": "ensure_dev_vm",
  "arguments": {
    "name": "integration-test"
  }
}

Execution Examples

6.安装依赖项

“跑 pip install -r requirements.txt 在“api服务器”VM内部。"

{
  "name": "exec_command",
  "arguments": {
    "vm_name": "api-server",
    "command": "pip install -r requirements.txt"
  }
}

7.构建和同步

将最新更改同步到“构建器”，然后运行 make build 立即。"

{
  "name": "exec_with_sync",
  "arguments": {
    "vm_name": "builder",
    "command": "make build"
  }
}

8.长期作业

“启动数据摄取脚本(python ingest.py)背景中的“数据湖”。"

{
  "name": "run_background_task",
  "arguments": {
    "vm_name": "data-lake",
    "command": "python ingest.py"
  }
}

File Operations Examples

9.部署配置

“上传我的本地 .env.production 文件到 /app/.env 在“worker node”虚拟机上。"

{
  "name": "upload_file",
  "arguments": {
    "vm_name": "worker-node",
    "source": ".env.production",
    "destination": "/app/.env"
  }
}

10.查找错误日志

“搜索名为的任何文件 error.log 里面 /var/log 目录。"

{
  "name": "search_files",
  "arguments": {
    "vm_name": "monitor",
    "query": "error.log",
    "path": "/var/log"
  }
}

11.设置文件监视器

“配置文件同步。映射我的本地 ./src 文件夹到 /usr/src/app 在“dev-main”上。"

{
  "name": "configure_sync",
  "arguments": {
    "vm_name": "dev-main",
    "host_path": "./src",
    "guest_path": "/usr/src/app",
    "direction": "bidirectional"
  }
}

12.冲突解决

“README.md上存在同步冲突。请使用我的本地版本。”

{
  "name": "resolve_conflict",
  "arguments": {
    "vm_name": "docs-site",
    "file_path": "README.md",
    "resolution": "use_host"
  }
}

Observability Examples

13.现场调试

“显示'proxy'VM上nginx错误日志的最后50行。”

{
  "name": "tail_vm_log",
  "arguments": {
    "vm_name": "proxy",
    "path": "/var/log/nginx/error.log",
    "lines": 50
  }
}

14.监控后台任务

“到目前为止，任务的输出是什么 task_12345?"

{
  "name": "get_task_output",
  "arguments": {
    "vm_name": "data-lake",
    "task_id": "task_12345"
  }
}

15.搜索日志

在“auth service”的系统日志中搜索任何“segfault”错误

{
  "name": "grep_log_stream",
  "arguments": {
    "vm_name": "auth-service",
    "path": "/var/log/syslog",
    "pattern": "segfault"
  }
}

Snapshot Examples

16.更新前备份

“我即将升级数据库。请保存一个名为'before-v14-upgrade'的快照。”

{
  "name": "snapshot_save",
  "arguments": {
    "vm_name": "postgres-primary",
    "snapshot_name": "before-v14-upgrade"
  }
}

17.灾难恢复

“升级失败！还原到'before-v14-upgrade'快照。”

{
  "name": "snapshot_restore",
  "arguments": {
    "vm_name": "postgres-primary",
    "snapshot_name": "before-v14-upgrade"
  }
}

18.列出快照

“‘kafka-broker’虚拟机有哪些快照可用？”

{
  "name": "snapshot_list",
  "arguments": {
    "vm_name": "kafka-broker"
  }
}

Process Control Examples

19.调查高负载

“‘ml trainer’VM运行缓慢。请列出正在运行的进程。”

{
  "name": "list_processes",
  "arguments": {
    "vm_name": "ml-trainer"
  }
}

20.杀死卡住进程

“进程ID 9982卡在‘worker-01’上。请将其终止。”

{
  "name": "kill_process",
  "arguments": {
    "vm_name": "worker-01",
    "pid": 9982,
    "signal": "SIGKILL"
  }
}

Network & Dashboard Examples

21.检查服务可用性

“端口8080是否打开并正在侦听'jenkins'VM？”

{
  "name": "check_vm_port",
  "arguments": {
    "vm_name": "jenkins",
    "guest_port": 8080
  }
}

22.系统健康仪表板

“给我一个包含CPU、RAM和磁盘使用情况的完整仪表板。”

{
  "name": "get_vm_dashboard",
  "arguments": {
    "vm_name": "production-replica"
  }
}

Progress & Download Examples

23.启动大下载

“将10GB数据集从example.com下载到 /data/ 在“ai模型”虚拟机上。"

{
  "name": "start_download",
  "arguments": {
    "vm_name": "ai-model",
    "url": "http://example.com/data.tar.gz",
    "destination": "/data/data.tar.gz"
  }
}

24.阻塞等待

“等待下载操作 op_5592 完成。"

{
  "name": "wait_for_operation",
  "arguments": {
    "operation_id": "op_5592",
    "timeout_seconds": 600
  }
}

System Maintenance Examples

25.检测僵尸虚拟机

“扫描系统，看看我们是否有任何孤立的僵尸虚拟机。”

{
  "name": "scan_system_health",
  "arguments": {}
}

26.清洁僵尸（干跑）

“看看如果我们清理了‘僵尸-1’和‘旧测试’会发生什么。”

{
  "name": "cleanup_zombies",
  "arguments": {
    "vm_names": ["zombie-1", "old-test"],
    "dry_run": true
  }
}

______________________________________________________________________

⚙️ MCP配置

克劳德桌面/鼠标/光标

添加到您的 claude_desktop_config.json 或 mcp_config.json:

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\Virtualbox-mcp-server\\apps\\mcp-server\\dist\\index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "PATH": "C:\\Program Files (x86)\\Vagrant\\bin;C:\\Program Files\\Oracle\\VirtualBox;%PATH%"
      }
    }
  }
}

🔥 前5个MCP配置示例

1.开发环境（Node.js+Docker）

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "node",
      "args": ["/home/user/Virtualbox-mcp-server/apps/mcp-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug",
        "VAGRANT_HOME": "/home/user/.vagrant.d",
        "VM_DEFAULT_BOX": "ubuntu/jammy64",
        "VM_DEFAULT_MEMORY": "4096",
        "VM_DEFAULT_CPU": "4"
      }
    }
  }
}

2.CI/CD管道（Jenkins/GitHub操作）

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "node",
      "args": ["/opt/mcp/vagrant-mcp-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "warn",
        "VAGRANT_HOME": "/var/lib/jenkins/.vagrant.d",
        "VM_AUTO_DESTROY": "true",
        "VM_SNAPSHOT_BEFORE_TEST": "true"
      }
    }
  }
}

3.Windows工作站

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "node.exe",
      "args": ["C:\\Users\\Developer\\mcp\\Virtualbox-mcp-server\\apps\\mcp-server\\dist\\index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "PATH": "C:\\Program Files (x86)\\Vagrant\\bin;C:\\Program Files\\Oracle\\VirtualBox;C:\\Windows\\System32",
        "VAGRANT_HOME": "C:\\Users\\Developer\\.vagrant.d"
      }
    }
  }
}

4.macOS与Homebrew

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/dev/Projects/Virtualbox-mcp-server/apps/mcp-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin",
        "VAGRANT_HOME": "/Users/dev/.vagrant.d"
      }
    }
  }
}

5.生产/企业（受限环境）

{
  "mcpServers": {
    "vagrant-mcp": {
      "command": "node",
      "args": ["/srv/mcp/vagrant-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "error",
        "VAGRANT_HOME": "/srv/vagrant",
        "VM_MAX_COUNT": "10",
        "VM_ALLOWED_BOXES": "company/base-ubuntu,company/base-centos",
        "VM_REQUIRE_SNAPSHOT": "true",
        "GUARDRAILS_STRICT": "true"
      }
    }
  }
}

______________________________________________________________________

🧪 发展

# Watch mode (rebuild on changes)
npm run dev

# Lint
npm run lint

# Format
npm run format

______________________________________________________________________

📝 许可证

MIT© 用户手册

______________________________________________________________________

由...制作❤️ 用于人工智能驱动的基础设施管理

⬆ 返回页首

Virtualbox MCP Server

快速接入

详细介绍

🖥️ VirtualBox MCP服务器

✨ 特性

📦 建筑

🚀 快速开始

先决条件

安装

运行服务器

🛠️ 全部38个工具

VM生命周期（6个工具）

执行（3个工具）

环境设置（3个工具）

文件操作（7个工具）

👁️ 可观察性（3个工具）

📸 快照（4个工具）

⚙️ 过程控制（2个工具）

🌐 网络（1个工具）

📊 仪表板（1个工具）

⏳ 进步意识（5个工具）

🛡️ 护栏和维护（2个工具）

🧠 人工智能推理（1个工具）

🔄 建筑工作流

🟢 简单的工作流程

1.“每日站立”（环境准备）

2.“数据集提取”（异步下载）

3.“服务脉冲”（基本调试）

🔴 高级工作流

4.“安全第一”更新（事务性回滚）

5.“资源回收”（系统卫生）

6.“深度修复”循环（智能调试）

💬 示例提示

1.提供新的数据库服务器

2.状态检查

3.库存概况

4.强制终止

5.临时环境检查

6.安装依赖项

7.构建和同步

8.长期作业

9.部署配置

10.查找错误日志

11.设置文件监视器

12.冲突解决

13.现场调试

14.监控后台任务

15.搜索日志

16.更新前备份

17.灾难恢复

18.列出快照

19.调查高负载

20.杀死卡住进程

21.检查服务可用性

22.系统健康仪表板

23.启动大下载

24.阻塞等待

25.检测僵尸虚拟机

26.清洁僵尸（干跑）

⚙️ MCP配置

克劳德桌面/鼠标/光标

🔥 前5个MCP配置示例

1.开发环境（Node.js+Docker）

2.CI/CD管道（Jenkins/GitHub操作）

3.Windows工作站

4.macOS与Homebrew

5.生产/企业（受限环境）

🧪 发展

📝 许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP