vagrant

The Vagrant MCP Server (Go implementation) provides AI-assisted management of development virtual machines via the Model Context Protocol. It enables AI agents to create, configure, start, stop, and destroy Vagrant-based VMs, while ensuring file synchronization between the host and the VM and allowing commands to be executed inside the VM with synchronized working directories. This server is intended to run directly on the host system where Vagrant and a virtualization provider are installed, since it requires access to the Vagrant CLI and virtualization drivers. It is not designed to run inside a container. Typical workflows include provisioning a VM for a project, installing language runtimes and toolchains inside the VM, synchronizing project files, running build/test commands inside the VM, and forwarding ports for development servers.

To use the MCP server, start the binary (for example, ./bin/vagrant-mcp-server). Once running, you can connect an AI assistant or editor integration (such as VS Code) configured to communicate over stdio (or the specified transport) and begin issuing prompts like: create a development VM for this project, run npm install in the VM, or set up a Python environment with virtualenv inside the VM. The prompts will be translated into MCP requests to manage VMs, execute commands, and synchronize files according to the configured environment.

Prerequisites

• Vagrant CLI installed and available in your PATH
• A virtualization provider (e.g., VirtualBox, VMware, Hyper-V, libvirt)
• Go 1.18+ if building from source (optional if using pre-built binaries)
• Internet access to download dependencies or pre-built binaries

Option A: Install via pre-built binary

1. Download the appropriate binary for your platform from the Releases page of the repository.
2. Make the binary executable (Linux/macOS):

chmod +x vagrant-mcp-server

3. Move the binary into your PATH (optional):

sudo mv vagrant-mcp-server /usr/local/bin/

4. Verify installation:

vagrant-mcp-server -version

Option B: Build from source

1. Clone the repository:

git clone https://github.com/vagrant-mcp/server.git vagrant-mcp-server
cd vagrant-mcp-server

2. Build the server (requires Go 1.18+):

make build

3. Start the server (stdio mode by default):

./bin/vagrant-mcp-server

Configuration after installation

• Set environment variables as needed (see the Configuration section in the README):
  • MCP_TRANSPORT (stdio or sse)
  • MCP_PORT (default 8080)
  • LOG_LEVEL
  • VM_BASE_DIR (default: ~/.vagrant-mcp-server/vms)

Notes and tips:

• This server is labeled as work in progress and not yet ready for production use. Expect ongoing changes and potential instability.
• The server must run on the host system with direct access to Vagrant and virtualization drivers. Running in Docker is not supported due to the need for direct VM access and file system synchronization.
• There is no built-in authentication in the MCP server itself; security relies on the surrounding environment (e.g., VS Code integration or other front-ends) and network exposure controls. Avoid exposing the SSE transport on public networks when using SSE mode.
• VM_BASE_DIR controls where VM state and files are stored; ensure it has enough space and proper permissions.
• When syncing files, consider enabling conflict resolution strategies and exclusion patterns for sensitive data.
• If you encounter issues, increase the log level to debug and inspect server logs for prompts and MCP protocol messages.