Skip to content

v2 MCP Server

Jump to bottom Edit New page
Eric Trenkel edited this page Sep 4, 2026 · 1 revision

MCP Server

Pro feature · BETA — see Free vs Pro.

The MCP server exposes your WSL environment (or your VMs on macOS) to AI agents through the Model Context Protocol — think of it as a terminal, but for your agent. Claude Desktop, Claude Code, opencode and any other MCP client can list your instances, create and configure them, run commands and hold real interactive shell sessions. The built-in AI assistant uses exactly the same tools.

Enable it under Settings → MCP Server (WSL API) (on macOS: MCP Server (VM API)).

MCP settings

Once enabled, the app shows the server URL and an access token:

MCP server enabled

Connecting a client

The server speaks streamable HTTP on http://127.0.0.1:59133/mcp and every request must carry the access token as a bearer token:

Authorization: Bearer <your token>

Copy both values with the buttons next to them. The eye icon reveals the token; the circular arrow generates a new one (any client using the old token stops working immediately).

Claude Desktop — click Connect Claude Desktop in the MCP panel. It writes the entry below into claude_desktop_config.json for you (needs Node.js); restart Claude Desktop afterwards. To do it by hand, or for any other stdio-only MCP client, bridge the HTTP endpoint with mcp-remote:

// claude_desktop_config.json  (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS)
{
  "mcpServers": {
    "wsl-manager": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:59133/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <TOKEN FROM THE MCP PANEL>" }
    }
  }
}

Claude Code — same bridge, one command:

claude mcp add wsl-manager -- npx -y mcp-remote http://127.0.0.1:59133/mcp \
  --header "Authorization: Bearer <TOKEN>"

opencode — add it under mcp in your opencode.json (or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "wsl-manager": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "http://127.0.0.1:59133/mcp",
                  "--header", "Authorization: Bearer <TOKEN>"]
    }
  }
}

Any MCP client that speaks streamable HTTP can also point straight at the endpoint with an Authorization: Bearer <TOKEN> header, skipping mcp-remote.

Available tools

Instances

Tool Purpose
wsl_list_distros List installed distros and which are running
wsl_distro_info State, install path and disk size of one distro
wsl_status WSL version, kernel, default distro and default WSL version
wsl_list_online_distros What wsl --list --online offers
wsl_list_catalog The app's own curated rootfs catalogue (name → URL)
wsl_install_distro wsl --install from the online catalogue, headless
wsl_import_distro Create a distro from a rootfs tarball (local path or URL)
wsl_import_in_place Register an existing .vhdx where it lies
wsl_export_distro Back up a distro to tar / tar.gz / tar.xz / vhd
wsl_package_distro / wsl_install_package Build or install a portable .wsl package
wsl_move_distro / wsl_resize_distro / wsl_compact_disk Move to another folder, grow the disk, compact it
wsl_set_default_distro / wsl_set_default_user / wsl_set_version Defaults and WSL 1 ↔ 2 conversion
wsl_stop_distro / wsl_shutdown Stop one distro, or all of WSL (needed for .wslconfig changes)
wsl_unregister_distro Permanently delete a distro — refuses unless confirm is true

Configuration, files and disks

Tool Purpose
wsl_get_wsl_conf / wsl_set_wsl_conf Read or set keys in a distro's /etc/wsl.conf
wsl_get_wslconfig / wsl_set_wslconfig Read or set keys in the global .wslconfig
wsl_copy_to / wsl_copy_from Copy a single file into or out of a distro
wsl_list_physical_disks / wsl_list_mounted_disks What can be mounted, what is mounted
wsl_mount_disk / wsl_unmount_disk wsl --mount / --unmount (Windows asks for admin rights)

Commands, snippets and recipes

Tool Purpose
wsl_run_command Run a shell command in an instance and return its output (default root, 300 s timeout; starts a stopped distro, a VM must be running)
wsl_terminal_start / _send / _read / _signal / _list / _close Persistent interactive shell sessions — send input, poll output, wait for a regex, send Ctrl-C / Ctrl-D / EOF, kill
wsl_list_snippets / _get_snippet / _create_snippet / _delete_snippet Manage saved snippets
wsl_list_recipes / wsl_install_service List and install the one-click service recipes (MinIO, Postgres, MySQL, ClickHouse, Redis, RabbitMQ, Kafka)

Virtual machines (macOS only)

Tool Purpose
vm_list_images The curated installer ISO and cloud image catalogue
vm_create_linux Create a Linux VM from a catalogue id, a local ISO or a disk image — a boot source is mandatory
vm_create_macos Create a macOS guest from a local .ipsw or the latest supported restore image (Apple Silicon)
vm_start Start a VM, headless or with its window
vm_ip The IP of a running VM, for SSH or reaching services inside it
vm_import_image Create a VM from an existing raw disk image, e.g. an exported template

The wsl_* instance, command, snippet and recipe tools work on VMs too — the names stay the same so agents don't need two vocabularies.

One-shot vs. sessions: wsl_run_command runs a command and returns when it finishes. The wsl_terminal_* tools keep a real shell alive across calls, which is what you want for a REPL, a build watcher, or anything that needs input after it has started. Closing the server (or quitting the app) closes any open terminal sessions.

Sandbox tools (sandbox_run_command, sandbox_read_file, sandbox_write_file, sandbox_terminal_*) are not served to external clients; they only exist inside sandbox chats.

Exposing it publicly (Cloudflare Tunnel)

By default the server is bound to 127.0.0.1 and is unreachable from any other machine — including others on your LAN.

If you need a remote client to reach it, the Expose via Cloudflare Tunnel toggle creates a temporary public HTTPS URL that forwards to your local server. No Cloudflare account is needed; the app downloads the cloudflared helper for your platform on first use, and the panel shows the Public URL with a copy button.

⚠️ Understand what this does. It puts your MCP server — and everything it can do, including creating, deleting and running commands in your instances — on the public internet. Your access token is the only thing protecting it. Treat that token like a password, only enable this when you actually need remote access, and turn it off when you're done. Stopping the MCP server also tears down the tunnel.

Security summary

  • Local-only by default (127.0.0.1), never LAN-exposed unless you opt in
  • Bearer token required on every request, regenerable at any time
  • Deleting a distro requires an explicit confirm flag; there is no tool that deletes a VM
  • The token is stored locally on your machine only
Add a custom footer
Add a custom sidebar

Clone this wiki locally