Provides an AI agent with a persistent virtual machine featuring a terminal, file system, and a visual Xfce desktop interface.
Also known as flujo-app/mcp-virtual-computer, mcp-virtual-computer
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- 202
- Latest version
- 0.2.11
- Last commit
- Oct 23, 2026
- License
- MIT
What is Virtual Computer MCP?
Virtual Computer provides an AI agent with a persistent virtual machine featuring a terminal, file system, and a visual Xfce desktop interface.
Summary generated from the project's README
About Virtual Computer MCP server
Providing an AI agent with a persistent virtual machine is what this server enables through a terminal, file system, and a visual Xfce desktop interface. Developers can run this environment locally using Docker Desktop or remotely via Fly.io machines. The setup supports both a virtual Three.js computer view and a real desktop environment, allowing users to interact with the same workspace as the model.
When running locally on Windows, the server can automatically prepare WSL 2 and install Docker Desktop. For remote deployment, it uses flyctl to build and manage a permanent machine that survives restarts. The agent can perform complex tasks using tools like terminal_execute, read_file, write_file, and edit_file. If the desktop environment is enabled, the model gains visual capabilities through look_at_screen and can interact with the interface using click, type, and scroll commands to manage Xfce windows.
What you can do with it
- 1Execute terminal commandsAn AI agent can run shell commands within a configured Docker container or Fly Machine.
- 2Manipulate files in workspaceThe model can perform atomic writes or precise text replacements within the virtual file system.
- 3Monitor visual stateThe model can capture the current screen state to understand the visual context of the desktop.
Written from the project's README. Every use case is checked against a quote from it.
How to install Virtual Computer MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Virtual Computer MCP in Claude Code
$ claude mcp add --env 'COMPUTER_ID=<COMPUTER_ID>' --env 'FLY_API_TOKEN=<YOUR_FLY_API_TOKEN>' mcp-virtual-computer -- uvx mcp-virtual-computerInstall Virtual Computer MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-virtual-computer": {
"command": "uvx",
"args": [
"mcp-virtual-computer"
],
"env": {
"COMPUTER_ID": "<COMPUTER_ID>",
"FLY_API_TOKEN": "<YOUR_FLY_API_TOKEN>"
}
}
}
}Install Virtual Computer MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-virtual-computer": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-virtual-computer"
],
"env": {
"COMPUTER_ID": "<COMPUTER_ID>",
"FLY_API_TOKEN": "<YOUR_FLY_API_TOKEN>"
}
}
}
}Install Virtual Computer MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-virtual-computer","type":"stdio","command":"uvx","args":["mcp-virtual-computer"],"env":{"COMPUTER_ID":"<COMPUTER_ID>","FLY_API_TOKEN":"<YOUR_FLY_API_TOKEN>"}}'Install Virtual Computer MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-virtual-computer": {
"command": "uvx",
"args": [
"mcp-virtual-computer"
],
"env": {
"COMPUTER_ID": "<COMPUTER_ID>",
"FLY_API_TOKEN": "<YOUR_FLY_API_TOKEN>"
}
}
}
}Install Virtual Computer MCP in Codex
$ codex mcp add mcp-virtual-computer --env 'COMPUTER_ID=<COMPUTER_ID>' --env 'FLY_API_TOKEN=<YOUR_FLY_API_TOKEN>' -- uvx mcp-virtual-computerInstall Virtual Computer MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-virtual-computer] command = "uvx" args = ["mcp-virtual-computer"] [mcp_servers.mcp-virtual-computer.env] COMPUTER_ID = "<COMPUTER_ID>" FLY_API_TOKEN = "<YOUR_FLY_API_TOKEN>"
Install Virtual Computer MCP in Gemini CLI
$ gemini mcp add -s user -e 'COMPUTER_ID=<COMPUTER_ID>' -e 'FLY_API_TOKEN=<YOUR_FLY_API_TOKEN>' mcp-virtual-computer uvx -- mcp-virtual-computerInstall Virtual Computer MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-virtual-computer": {
"command": "uvx",
"args": [
"mcp-virtual-computer"
],
"env": {
"COMPUTER_ID": "<COMPUTER_ID>",
"FLY_API_TOKEN": "<YOUR_FLY_API_TOKEN>"
}
}
}
}Configuration
COMPUTER_IDRequiredStable identity of the one persistent computer.
FLY_API_TOKENSecretOptional Fly API token. A cached flyctl login is also supported.
AUTO_INSTALL_DOCKEROn Windows, install and start Docker Desktop lazily when needed.
AUTO_INSTALL_FLYCTLDownload flyctl into the user profile when it is missing.
BACKENDComputer provider. Use docker for a local container or fly for a permanent Fly Machine.
DESKTOP_ENVIRONMENTStart the real Xfce desktop instead of the virtual desktop.
EXPOSE_LIFECYCLE_TOOLSAlso expose runtime status and network/desktop switching tools to the model. The MCP App can always use them.
NETWORK_ACCESSAllow outbound network access from the computer.
| Name | Description | |
|---|---|---|
| COMPUTER_ID | Stable identity of the one persistent computer. | Required |
| FLY_API_TOKEN | Optional Fly API token. A cached flyctl login is also supported. | Secret |
| AUTO_INSTALL_DOCKER | On Windows, install and start Docker Desktop lazily when needed. | |
| AUTO_INSTALL_FLYCTL | Download flyctl into the user profile when it is missing. | |
| BACKEND | Computer provider. Use docker for a local container or fly for a permanent Fly Machine. | |
| DESKTOP_ENVIRONMENT | Start the real Xfce desktop instead of the virtual desktop. | |
| EXPOSE_LIFECYCLE_TOOLS | Also expose runtime status and network/desktop switching tools to the model. The MCP App can always use them. | |
| NETWORK_ACCESS | Allow outbound network access from the computer. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubMCP Virtual Computer
A VM for your agent. And for you.
- click the mug to switch between a virtual desktop or a real one
- unplug the network cable and cut network access
- use the computer screen like a normal screen
- copy and paste text between the host browser and the Xfce desktop
- model can use terminal, create/read/edit files, see the screen, click, type
- little fun thing: if either you or the llm types text, you see that on the keyboard; if one uses the cursor, you see the mouse move on the table.
- automatically installs Docker Desktop on Windows for local mode, or flyctl for Fly mode
MCP client example
Local Docker (default)
COMPUTER_ID defaults to agent-workstation when omitted. Set it explicitly to
keep using a named computer or to create a separate one. On a fresh Windows PC,
setup prepares WSL 2 before installing Docker Desktop. Approve the Windows
administrator prompt if shown; if a restart is required, restart Windows, reopen
your MCP client, and retry. See Windows first-use validation.
{
"mcpServers": {
"virtual-computer": {
"command": "uvx",
"args": ["mcp-virtual-computer"],
"env": {
"COMPUTER_ID": "agent-workstation",
"DESKTOP_ENVIRONMENT": "true",
"NETWORK_ACCESS": "true",
"AUTO_INSTALL_DOCKER": "true",
"EXPOSE_LIFECYCLE_TOOLS": "false"
}
}
}
}
Fly.io Machine
On a fresh machine, start the MCP once, run the exact flyctl auth login command shown by its error, and restart the MCP client
{
"mcpServers": {
"virtual-computer-fly": {
"command": "uvx",
"args": ["mcp-virtual-computer", "--backend", "fly"],
"env": {
"COMPUTER_ID": "agent-workstation",
"DESKTOP_ENVIRONMENT": "true",
"NETWORK_ACCESS": "true",
"AUTO_INSTALL_FLYCTL": "true",
"EXPOSE_LIFECYCLE_TOOLS": "false"
}
}
}
}
What it exposes
terminal_execute— run a command in the configured Docker container or Fly Machine.read_file— read a UTF-8 text file relative to/workspaceor by absolute path.write_file— atomically write a UTF-8 text file.edit_file— replace one exact text match, or all matches when requested.computer_ui— open or attach the Three.js computer view. Its result includes both the MCP Appresource_uriand a real loopbackurl/dashboard_urlthat opens in an external browser, including for stdio clients.
DESKTOP_ENVIRONMENT defaults to true. With the real desktop enabled it
additionally exposes:
look_at_screen— return the current PNG framebuffer, AT-SPI snapshot, or both.click,type, andscroll— interact by AT-SPI element reference or coordinates.list_windowsandswitch_window— enumerate and activate real Xfce windows.move_window,maximize_window,restore_window,minimize_window, andclose_window— control a selected window by ID, title, or class.computer://screen/current.png— current live framebuffer resource.computer://screen/accessibility.json— Playwright-like AT-SPI tree with element refs, roles, names, actions, focus state, and screen bounds.
The MCP App can always call runtime_status, set_network_access, and set_desktop_environment. Set EXPOSE_LIFECYCLE_TOOLS=true to additionally expose those lifecycle controls to the model; they remain model-hidden by default.
Architecture
Demo: FLUJO
Demo: Claude Desktop
Demo: Goose
Permanent Fly Machine
Fly mode builds the bundled Xfce image with Fly's remote builder and deploys it as one permanent Machine. The root filesystem and /workspace survive MCP restarts, and the Three.js screen uses the same noVNC desktop through Fly's HTTPS/WebSocket proxy.
This is the Xfce framebuffer returned by look_at_screen from a deployed Fly Machine. The same live desktop appears on the rendered computer after computer_ui connects to VNC:

No app name, region, CPU size, memory size, Docker installation, or VNC configuration is required.
The package's MCP Registry declaration, including the docker and fly backend choices, is in server.json. See Fly setup for the complete first-run and authentication flow.
On first use, virtual-computer finds fly/flyctl or downloads the current official release to ~/.fly/bin. It uses a cached fly auth login session or FLY_API_TOKEN, selects the personal organization when available, creates and remembers a generated app, lets Fly choose the closest placement, and defaults to one shared CPU with 1 GB RAM.
Authentication is the only unavoidable account step. On a fresh machine, start the MCP once, run the exact flyctl auth login command shown by its error, and restart the MCP client. The first computer call can take several minutes while Fly remotely builds Xfce. Later starts attach to the same Machine.
Optional overrides remain available as FLY_ORG, FLY_APP_NAME, FLY_REGION, FLY_API_TOKEN, and the --fly-* flags. Set AUTO_INSTALL_FLYCTL=false to require a preinstalled CLI. Deleting or factory-resetting the computer destroys its persistent Fly root filesystem; ordinary MCP shutdown leaves the permanent Machine running. Stop or delete it from Fly when you no longer want it to incur usage.
License and origin
MIT licensed. This project is a persistent-computer fork of Kilntainers with Docker and Fly backends.
Virtual Computer MCP questions
How do I add Virtual Computer MCP to Claude Code?
Run claude mcp add --env 'COMPUTER_ID=<COMPUTER_ID>' --env 'FLY_API_TOKEN=<YOUR_FLY_API_TOKEN>' mcp-virtual-computer -- uvx mcp-virtual-computer in your terminal. Add --scope user to make it available in every project.
How do I add Virtual Computer MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can the model do within the virtual computer?
The model can use the terminal, create, read, and edit files, see the screen, and interact via clicking and typing.
How does the virtual computer persist data?
When using Fly mode, the root filesystem and /workspace survive MCP restarts.
Can I control network access for the agent?
Yes, you can unplug the network cable to cut network access.