wsl-bridge-mcp
wsl-bridge-mcp lets a Windows-side AI agent operate WSL distros like a local environment — reading/writing files, running commands, managing background processes and logs, searching, and inspecting system state — with no installs inside WSL.
Discover & inspect:
list_distros,get_system_info,check_wsl_status,diagnose,list_ports,get_envPath handling:
translate_path(POSIX ↔ UNC/Windows),resolve_path(~, ., .. to absolute)File operations (UNC/9P via Node
fs, nowsl.exespawn):read_file,read_multiple_files,write_file,edit_file,list_directory(paginated),get_file_info,create_directory,move_file,delete_pathCommand execution:
run_command(foreground, multi-line, cwd/env/timeout, separate stderr, binary output),set_cwdfor the persistent shellProcess & log management:
start_process,get_process_status,read_process_output(offset-based, follow + notification streaming, stdout/stderr),list_processes,stop_processSearch:
search_files(find by glob),search_content(ripgrep/grep recursive content search)Env management:
set_envthat persists acrossrun_commandcallsAuditing & history:
query_audit_log,query_command_history(recent commands and background-process launch results)Guarantees: guardrails blocking catastrophic commands (with optional confirm), optional path sandboxing, permission modes (compat/read-only/workspace/allowlist), output truncation limits, and credential-masked audit logging
Provides tools for interacting with Linux distributions via Windows Subsystem for Linux (WSL), enabling file reading/writing/editing, command execution, process management, log streaming, and content search in the Linux environment.
Supports Ubuntu WSL distributions as a target, allowing AI agents to perform file operations, run commands, manage processes, and search content within an Ubuntu instance via the WSL bridge.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wsl-bridge-mcp Check if nginx is running in my WSL Ubuntu and stream the error log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wsl-bridge-mcp
一个 MCP 服务器,让 Windows 侧的 AI 编程代理(Claude Code、Codex、OpenCode)可以像操作本地环境一样操作 WSL 发行版:读写/编辑文件、执行命令、管理长驻进程、流式查看日志、搜索文件内容——全部由运行在 Windows 上的代理完成。
WSL 内部零安装。 只依赖系统自带的 wsl.exe 和 Windows 对 WSL 文件系统的 UNC 访问视图。
工作原理
双通道设计兼顾低延迟,同时绕开常见的 WSL 桥接坑:
Agent(Windows,MCP 客户端)──stdio──▶ wsl-bridge-mcp(Windows,TS/Node)
│
┌───────────────┴────────────────┐
▼ ▼
文件通道(UNC) 执行通道(常驻 shell)
\\wsl.localhost\<distro>\… wsl.exe -d <distro> -- stdbuf -o0 bash
Node fs,二进制安全 每个发行版一个,哨兵帧协议
│ │
└───────── 路径转换 ──────────────┘
+ 护栏 + 审计日志文件操作 走
\\wsl.localhost\<distro>\…(9P 协议),通过 Nodefs完成——不派生wsl.exe,二进制安全,速度快。命令执行 / 搜索 / 进程管理 走每个发行版一个的长驻
wsl.exe … bash进程,使用哨兵标记帧协议——摊薄了约 50–150ms 的派生开销,并提供真正的管道用于流式输出。路径转换 集中处理并带缓存;代理侧统一使用 POSIX 路径。
护栏 拦截灾难性命令(
rm -rf /、dd of=/dev/sd*、fork 炸弹等),支持可选确认;另提供可选的路径沙箱和完整审计日志。
Related MCP server: SSH MCP Server
安装
npm install -g wsl-bridge-mcp
# 或者不安装直接使用:
npx wsl-bridge-mcp要求 Node ≥ 20 和一个 WSL2 发行版(\\wsl.localhost 推荐在 Windows 11 上使用)。
配置
配置是可选的。只要设置了默认发行版,默认值即可开箱即用。
优先级:环境变量(WSL_BRIDGE_*)> .wsl-bridge.json(从当前工作目录向上查找)> 默认值。
将 .wsl-bridge.example.json 复制为 .wsl-bridge.json(或设置环境变量):
配置项 | 环境变量 | 默认值 | 说明 |
|
| — | 工具未指定 |
|
| 30000 |
|
|
| 120000 | 长耗时操作(搜索、系统信息)超时 |
|
| 1048576 | 输出截断上限 |
|
|
|
|
|
|
| POSIX 路径;为空 = 整个发行版 |
|
|
| 审计日志目录(Windows 侧) |
|
|
| 启动时预派生默认发行版的 shell(消除首条命令的延迟) |
|
|
|
|
|
|
| 分号分隔的完整命令正则(allowlist 模式) |
|
|
| 命令路径策略护栏 |
|
| 8388608 | 批量文件读取总字节预算 |
|
| 1000 | 搜索结果条目上限 |
|
| 67108864 | 单次进程日志读取预算 |
|
| 4 | 高资源工具并发上限 |
|
| 10485760 | 单个审计文件大小 |
|
| 3 | 审计轮换文件数量 |
|
| 0 | 前台命令输出写入历史的最大字节数;0 不持久化输出,最多 16384 |
sandboxDirs 在环境变量中使用 ; 分隔。
permissionMode=compat 保持现有行为;read-only 仅允许检查类命令并禁止写入、后台进程和 set_env;workspace 要求修改和命令工作目录位于 sandboxDirs;allowlist 要求命令完整匹配白名单并拒绝常见 Shell 元字符。它们是应用层防误操作护栏,不等于容器、虚拟机或操作系统级隔离。审计日志会掩码常见凭据,文件写入只记录字节数和 SHA-256,并按大小轮换。
连接你的代理
Claude Code
claude mcp add wsl-bridge -- node /path/to/wsl-bridge-mcp/dist/server.js
# 或已全局安装 / 通过 npx:
claude mcp add wsl-bridge -- npx wsl-bridge-mcp在服务器配置中通过环境变量设置默认发行版,或在每次调用时传入 distro。
Codex
添加到 Codex 的 MCP 配置(~/.codex/config.toml 或等效位置):
[mcp_servers.wsl-bridge]
command = "npx"
args = ["wsl-bridge-mcp"]
env = { WSL_BRIDGE_DISTRO = "Ubuntu-24.04" }OpenCode
添加到 OpenCode 的 MCP 配置(例如 opencode.json):
{
"mcp": {
"wsl-bridge": {
"type": "local",
"command": ["npx", "wsl-bridge-mcp"],
"environment": { "WSL_BRIDGE_DISTRO": "Ubuntu-24.04" }
}
}
}工具(29 个)
发现类: list_distros、get_system_info、check_wsl_status
路径类: translate_path、resolve_path
文件类(UNC): read_file、read_multiple_files、write_file、edit_file、list_directory、get_file_info、create_directory、move_file、delete_path
执行类: run_command、set_cwd
进程与日志: start_process、get_process_status、read_process_output、list_processes、stop_process
搜索类: search_files、search_content
辅助类: list_ports、get_env、set_env、diagnose、query_audit_log、query_command_history
查询最近命令和项目启动结果
调用 query_command_history,例如传入 { "sinceMinutes": 60, "limit": 20, "distro": "Ubuntu-26.04" },可以看到最近通过本 MCP 执行的 run_command 和 start_process,包含命令、工作目录、状态、退出码、错误和进程 handle。start_process 的 stdout/stderr 尾部会按需从 WSL 进程日志读取(单条最多 4096 字节);日志仍在时,重启 MCP 后也可查询启动结果。长时间运行的项目可继续通过 read_process_output 跟踪日志(同一个 MCP 进程内使用 handle)。
前台命令输出默认不写入历史,只记录退出码和错误状态。若要在后续调用中查看运行输出,设置 commandHistoryOutputBytes(例如 4096),或在 MCP 服务环境中设置 WSL_BRIDGE_COMMAND_HISTORY_OUTPUT_BYTES=4096,然后重启 MCP。历史输出仅保存截断后的脱敏预览,不能保证识别所有自定义凭据;不要在可能输出高敏数据的环境中开启。二进制输出不入历史。旧审计记录没有输出字段,后台日志被清理后也无法追溯其内容。历史查询受审计轮换和读取预算限制,不记录绕过 MCP 直接执行的命令。
性能、流式输出与保真度
部分工具参数可解锁更低延迟、真正的流式输出和可校验的二进制传输:
延迟
/mnt/<盘符>直连访问 —— 对/mnt/c/...等 drvfs 路径的文件操作会通过 Nodefs直接解析到 Windows 盘符(C:\...),完全跳过 WSL/9P。其他路径(/home、/tmp、/mnt/wsl等)仍走 UNC。适用时translate_path会报告直连的windowsPath。盘符只探测一次并缓存。list_directory分页 —— 传入offset/limit可对大目录分页遍历,只对返回的当前页做stat。响应中包含total、offset、limit、hasMore。Shell 预热 ——
prewarmShells: true(默认)会在启动时派生默认发行版的 shell,让第一条命令不必承担wsl.exe的派生开销。
流式输出与 stderr
run_command/start_process的separateStderr: true—— 单独捕获 stderr,而不是合并进 stdout。此时run_command返回独立的stdout和stderr;start_process会写入一个.err文件,可通过read_process_output加which: "stderr"读取。read_process_output的stream: true—— 在 follow 期间,将每个新数据块以notifications/message推送(客户端传了progressToken时还会推送notifications/progress),然后返回最终偏移量。无需轮询即可实时收到日志;无论客户端是否忽略通知,最终负载都会完整返回,不会丢数据。内存安全读取 ——
read_file通过文件描述符只读取所需字节(利用offset/limit/maxBytes),超大文件不会整体加载进内存。
二进制保真
read_file/write_file的sha256: true—— 返回(读/写的)字节的sha256。写入后读取并比对哈希,即可验证字节级精确往返。write_file还会回显mimeType。
安全性
护栏 会扫描每个
run_command/start_process命令中的危险模式。灾难性命令(rm -rf /、块设备写入、fork 炸弹、mkfs)被硬性拦截;有风险但可逆的命令(shutdown、chmod -R /)需要confirm=true。可通过guardrailMode调整。rm的目标会被规范化(去引号、去尾部斜杠),因此带引号的根目录 /$HOME/~/写法也能被捕获。路径沙箱(
sandboxDirs):设置后,修改类文件操作被限制在允许列表内,并会在 Linux 侧解析符号链接(realpath -m),因此沙箱内的符号链接无法逃逸。(符号链接解析刻意放在 Linux 侧:WSL 9P 会把符号链接呈现为 Windows 上的不透明 reparse 点,fs.realpath无法穿透。)默认关闭。Shell 安全输入:环境变量名(
run_command/start_process的 env、set_env/get_env的名称)必须是合法的 POSIX 标识符并被 shell 引用;stop_process只接受大写信号枚举(TERM、KILL、INT等),并如实报告sent/exitCode。搜索模式使用单引号包裹,因此$、反引号和引号会被字面匹配,绝不会被执行。配置校验:
.wsl-bridge.json的值按配置项逐项校验(zod);无效条目会向 stderr 告警并回退到默认值,而不是崩溃或静默异常。超时环境变量被限制为>= 0——0表示显式禁用超时。审计日志:每次工具调用(工具名、参数摘要、状态、耗时、发行版)都会追加到
logDir下的audit.log。可通过query_audit_log查询。输出上限:大输出会被截断到
maxOutputBytes,并附带提示。
故障排查
运行命令时出现
Wsl/Service/E_UNEXPECTED:WSL 服务状态异常,尽管发行版显示为 Running 且 UNC 正常。用wsl --shutdown修复(会重启所有发行版——关闭 WSL 中正在运行的进程),然后重试。此状态下文件通道工具仍然可用。No distro specified:设置WSL_BRIDGE_DISTRO或defaultDistro,或在每次调用时传distro。运行list_distros查看发行版名称。UNC 不可达:确保发行版已启动(
wsl -d <distro> echo ok)。优先使用\\wsl.localhost(Win11+);\\wsl$是备选方案。运行
diagnose工具对 UNC、shell 和权限做一次通过/失败的全项检查。
开发
npm install
npm run build # tsc -> dist/
npm run typecheck # 类型检查 src + tests
npm test # 仅单元测试(无需 WSL)
npm run test:integration # 针对真实 WSL 发行版的集成测试
npm run test:smoke # 构建并在 stdio 上冒烟测试服务器
npm run test:e2e # 构建并在 stdio 上跑完整 e2e 套件
npm run dev # tsx watch设置 WSL_BRIDGE_DISTRO=<你的发行版>,可让 e2e/smoke/integration 脚本针对非默认发行版运行。
Available Tools
28 toolscheck_wsl_statusA
Health check: confirm a WSL distro is reachable and the persistent shell responds.
Inputs: distro.
create_directoryC
Create a directory in WSL (recursive).
Inputs: path (required), distro.
delete_pathA
Delete a file or directory in WSL. Recursive directory deletion requires recursive=true and may require confirm=true for shallow paths (guardrail).
Inputs: path (required), distro, confirm, recursive.
diagnoseA
Run a diagnostic sweep: distros, UNC reachability, persistent shell, /tmp/wsl-bridge, and a UNC write/read probe. Returns a pass/fail report.
Inputs: distro.
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.
Inputs: path (required), newString (required), oldString (required), distro, +2 more.
get_envA
Read environment variables from the persistent WSL shell. Pass name for one var, or omit for all.
Inputs: name, distro.
get_file_infoB
Stat a WSL path: type, size, mode, mtime, atime.
Inputs: path (required), distro.
get_process_statusA
Check whether a started process is still running, and its exit code if finished.
Inputs: handle (required).
get_system_infoA
Get WSL system info (OS, kernel, uptime, memory, disk, user) for a distro.
Inputs: distro.
list_directoryA
List entries in a WSL directory, with type and size. Directories sort first. Supports offset/limit pagination for large directories.
Inputs: path (required), limit, distro, offset.
list_distrosB
List installed WSL distributions with their state and version, and mark the default.
Inputs: no named parameters.
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).
Inputs: distro.
list_processesA
List all processes started via start_process that this server is tracking.
Inputs: no named parameters.
move_fileC
Move or rename a file/directory within WSL.
Inputs: to (required), from (required), distro.
query_audit_logA
Query the audit log of past tool calls (most-recent-first). Filter by tool, since (ISO timestamp), or keyword.
Inputs: tool, limit, since, keyword.
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.
Inputs: path (required), limit, distro, offset, +1 more.
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.
Inputs: paths (required), distro.
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.
Inputs: handle (required), limit, which, follow, +4 more.
resolve_pathA
Resolve a possibly-relative WSL POSIX path (handles ~, ., ..) to an absolute POSIX path, using a working directory and the distro home.
Inputs: path (required), cwd, distro.
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).
Inputs: command (required), cwd, env, distro, +4 more.
search_contentA
Search file contents in WSL (recursive grep). Returns file:line:match entries. Uses ripgrep if available, else falls back to grep.
Inputs: path (required), pattern (required), distro, include, +1 more.
search_filesA
Find files in WSL by name pattern (find -name). Returns matching POSIX paths.
Inputs: path (required), pattern (required), distro, maxDepth.
set_cwdA
Set the persistent shell working directory for a distro. Subsequent run_command calls without an explicit cwd will run here.
Inputs: cwd (required), distro.
set_envA
Set an environment variable in the persistent WSL shell (persists across run_command calls).
Inputs: name (required), value (required), distro.
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.
Inputs: command (required), cwd, env, distro, +2 more.
stop_processA
Send a signal to a started process (default SIGTERM). Use signal=KILL to force. Uppercase signal names only.
Inputs: handle (required), signal.
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.
Inputs: path (required), distro, direction.
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.
Inputs: path (required), content (required), distro, sha256, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceNode.js server implementing Model Context Protocol that enables seamless interaction between Windows and Linux distributions under WSL, allowing file operations like reading, writing, searching, and managing files across the WSL filesystem from Windows.21 npm16MIT
- FlicenseAqualityDmaintenanceA local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.62-
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables Claude Desktop to execute bash commands and scripts in WSL2 Linux distributions on Windows.6MIT
- AlicenseNot gradedqualityBmaintenanceThis MCP server lets Windows-based AI agents execute bash commands, read and write files, list directories, and translate paths between Windows and Linux formats across installed WSL distributions. It runs each operation through wsl.exe with real exit codes, supports a read-only mode, and can target a specific distro or fall back to the default one.MIT