Skip to main content
Glama

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 协议),通过 Node fs 完成——不派生 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(或设置环境变量):

配置项

环境变量

默认值

说明

defaultDistro

WSL_BRIDGE_DISTRO

—

工具未指定 distro 时使用的发行版

commandTimeoutMs

WSL_BRIDGE_COMMAND_TIMEOUT_MS

30000

run_command 超时

scriptTimeoutMs

WSL_BRIDGE_SCRIPT_TIMEOUT_MS

120000

长耗时操作(搜索、系统信息)超时

maxOutputBytes

WSL_BRIDGE_MAX_OUTPUT_BYTES

1048576

输出截断上限

guardrailMode

WSL_BRIDGE_GUARDRAIL_MODE

block-and-confirm

block-and-confirm / block / off

sandboxDirs

WSL_BRIDGE_SANDBOX_DIRS

[]

POSIX 路径;为空 = 整个发行版

logDir

WSL_BRIDGE_LOG_DIR

%APPDATA%\wsl-bridge-mcp

审计日志目录(Windows 侧)

prewarmShells

WSL_BRIDGE_PREWARM_SHELLS

true

启动时预派生默认发行版的 shell(消除首条命令的延迟)

permissionMode

WSL_BRIDGE_PERMISSION_MODE

compat

compat、read-only、workspace、allowlist

commandAllowlist

WSL_BRIDGE_COMMAND_ALLOWLIST

[]

分号分隔的完整命令正则(allowlist 模式)

sensitivePaths

WSL_BRIDGE_SENSITIVE_PATHS

/etc;/root;/boot;/dev;/proc;/sys;/var/run;/var/lib

命令路径策略护栏

maxBatchBytes

WSL_BRIDGE_MAX_BATCH_BYTES

8388608

批量文件读取总字节预算

maxSearchResults

WSL_BRIDGE_MAX_SEARCH_RESULTS

1000

搜索结果条目上限

maxProcessLogBytes

WSL_BRIDGE_MAX_PROCESS_LOG_BYTES

67108864

单次进程日志读取预算

maxConcurrentCalls

WSL_BRIDGE_MAX_CONCURRENT_CALLS

4

高资源工具并发上限

auditMaxBytes

WSL_BRIDGE_AUDIT_MAX_BYTES

10485760

单个审计文件大小

auditRetentionFiles

WSL_BRIDGE_AUDIT_RETENTION_FILES

3

审计轮换文件数量

commandHistoryOutputBytes

WSL_BRIDGE_COMMAND_HISTORY_OUTPUT_BYTES

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 路径的文件操作会通过 Node fs 直接解析到 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 tools
check_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

    A3.6/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Node.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 npm
      16
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.
      6
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      This 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