wsl-bridge-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| WSL_BRIDGE_DISTRO | No | The default WSL distribution to use when the tool does not specify a `distro`. | |
| WSL_BRIDGE_LOG_DIR | No | Directory for audit logs (Windows side). | %APPDATA%\wsl-bridge-mcp |
| WSL_BRIDGE_SANDBOX_DIRS | No | Semicolon-separated list of POSIX paths allowed for modifying file operations. Empty means the entire distro. | [] |
| WSL_BRIDGE_GUARDRAIL_MODE | No | Guardrail mode: 'block-and-confirm', 'block', or 'off'. | block-and-confirm |
| WSL_BRIDGE_PREWARM_SHELLS | No | Whether to pre-spawn default distro shell on startup to eliminate first command latency. | true |
| WSL_BRIDGE_MAX_OUTPUT_BYTES | No | Maximum output size in bytes before truncation. | 1048576 |
| WSL_BRIDGE_SCRIPT_TIMEOUT_MS | No | Timeout for long-running operations such as search and system info in milliseconds. | 120000 |
| WSL_BRIDGE_COMMAND_TIMEOUT_MS | No | Timeout for `run_command` in milliseconds. | 30000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_distrosB | List installed WSL distributions with their state and version, and mark the default. |
| get_system_infoA | Get WSL system info (OS, kernel, uptime, memory, disk, user) for a distro. |
| check_wsl_statusA | Health check: confirm a WSL distro is reachable and the persistent shell responds. |
| translate_pathA | Translate a WSL POSIX path to a Windows UNC path, or vice versa. Useful for understanding where a WSL file lives on the Windows side. |
| resolve_pathA | Resolve a possibly-relative WSL POSIX path (handles ~, ., ..) to an absolute POSIX path, using a working directory and the distro home. |
| read_fileA | Read a file from WSL. Text files return UTF-8 content; binary files return base64 with a mimeType. Supports offset/limit for large files; sha256=true returns a hash of the read bytes for round-trip verification. |
| read_multiple_filesA | Read multiple files from WSL in one call (reduces round-trips). Each entry is returned independently; failures do not abort the batch. |
| write_fileA | Write a file in WSL. content is UTF-8 text by default; set encoding="base64" for binary content. Creates parent directories as needed. sha256=true returns a hash of the written bytes for round-trip verification. |
| edit_fileA | Line/substring-based edit of a WSL file: replace oldString with newString. oldString must be unique unless replaceAll=true. Use dryRun=true to preview. |
| list_directoryA | List entries in a WSL directory, with type and size. Directories sort first. Supports offset/limit pagination for large directories. |
| get_file_infoB | Stat a WSL path: type, size, mode, mtime, atime. |
| create_directoryC | Create a directory in WSL (recursive). |
| move_fileC | Move or rename a file/directory within WSL. |
| delete_pathA | Delete a file or directory in WSL. Recursive directory deletion requires recursive=true and may require confirm=true for shallow paths (guardrail). |
| run_commandA | Run a shell command in WSL (foreground, waits for completion). Supports multi-line scripts, cwd, env vars, and timeout. Returns stdout (and stderr, separately when separateStderr=true; otherwise stderr is merged into stdout) and exit code. Dangerous commands are blocked by the guardrail (confirm=true overrides confirmable ones). |
| set_cwdA | Set the persistent shell working directory for a distro. Subsequent run_command calls without an explicit cwd will run here. |
| start_processA | Start a long-running process in WSL (backgrounded). Returns a handle and pid; output is streamed to a log file readable via read_process_output. |
| get_process_statusA | Check whether a started process is still running, and its exit code if finished. |
| read_process_outputA | Read new output from a started process log, incrementally by byte offset. Pass follow=true to briefly wait for new output; stream=true to additionally push each new chunk as a notifications/message (and notifications/progress when the client sent a progressToken) as it arrives. which selects stdout (default) or stderr. Returns the next offset to use. |
| list_processesA | List all processes started via start_process that this server is tracking. |
| stop_processA | Send a signal to a started process (default SIGTERM). Use signal=KILL to force. Uppercase signal names only. |
| search_filesA | Find files in WSL by name pattern (find -name). Returns matching POSIX paths. |
| search_contentA | Search file contents in WSL (recursive grep). Returns file:line:match entries. Uses ripgrep if available, else falls back to grep. |
| list_portsA | List TCP ports listening in WSL (via ss, falling back to /proc/net/tcp). Useful to find where a dev server is reachable (WSL2 forwards localhost to Windows). |
| get_envA | Read environment variables from the persistent WSL shell. Pass name for one var, or omit for all. |
| set_envA | Set an environment variable in the persistent WSL shell (persists across run_command calls). |
| diagnoseA | Run a diagnostic sweep: distros, UNC reachability, persistent shell, /tmp/wsl-bridge, and a UNC write/read probe. Returns a pass/fail report. |
| query_audit_logA | Query the audit log of past tool calls (most-recent-first). Filter by tool, since (ISO timestamp), or keyword. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 28 tools
Each tool targets a distinct resource and action: file operations, process management, environment variables, and system queries are cleanly separated. Even similar tools like run_command vs start_process or read_file vs read_multiple_files have clear behavioral differences. No two tools appear to do the same thing.
Tool names consistently follow a verb_noun pattern in snake_case, such as write_file, list_directory, get_system_info, and stop_process. Minor exceptions like diagnose or check_wsl_status still fit the general style. The naming is predictable and makes it easy to infer what each tool does.
With 28 tools, this exceeds the 25-tool threshold considered 'too many', though the broad scope of a WSL bridge justifies many of them. Still, consolidation is possible, e.g., merging get_file_info into list_directory or having diagnose call other tools. The set feels heavy even if each tool is individually useful.
The tool surface covers a comprehensive set of WSL operations: file CRUD and search, process execution and management, environment controls, system information, path translation, and an audit log. A minor gap is the lack of distro lifecycle management (start/stop/shutdown), but that is not essential for typical bridging tasks. Core workflows are fully covered with no dead ends.