WinExec MCP for Remote-SSH

中文 | English

中文

自包含扩展（exe + 源码 + 自动配置）：让 Remote-SSH（Linux）端运行的 AI agent（Copilot、Claude Code 等）在 Windows 客户端执行任意命令——CLI、脚本、Windows 特有命令、串口/硬件工具均可——立即返回 stdout/stderr/exit code（UTF-8）。

界面文案跟随 VS Code 显示语言（简体中文 / English），无需手动切换。

安装即用

code --install-extension win-exec-mcp-0.6.12.vsix

→ Reload Window → 首次激活弹窗，按用途二选一：

• 完整配置（含服务器端 agent）：除 VS Code 内建 agent 外，同时追加 ~/.ssh/config 的 RemoteForward（先备份）并向当前项目写入根 .mcp.json（含 token；VS Code 与 Claude Code / Cursor 都读这一个文件，单一来源避免重复注册）—— 服务器端的 Claude Code / Cursor 等直接可用，无需手改任何文件
• 仅 VS Code：只注册用户级 mcp.json + 自动启动/连接本机 HTTP 服务；外部 agent 部分可随时用命令补齐（不会自动启用）

授权一次，之后全自动：点过「同意/完整配置」的用户（含从旧版本升级）在远端窗口会自动维护 SSH RemoteForward 与项目注册（URL/token）：缺失就补、过期就改，修复后提示「已修复配置文件，需重载窗口生效」（未打开项目时项目注册等打开后自动完成）。选「仅 VS Code」或点过「暂不」则外部配置保持关闭；重新运行 WinExec MCP: Enable / Re-run setup (consent) 可随时改选。排查看「输出 → WinExec MCP」日志。

拒绝（暂不）不会写入任何文件、不会拉起进程；之后可用命令 WinExec MCP: Enable / Re-run setup (consent) 或 Register user mcp.json 随时启用。

双模式

• stdio（win-exec-mcp）：注册到用户级 mcp.json（location: local），Windows 客户端拉起进程，走 Remote-SSH 通道 —— VS Code 内建 agent 可用；Remote-SSH 窗口不注册（http 条目已覆盖内建 agent，两个都在会重复工具），WSL / 本地窗口照旧
• http：注册到项目根 .mcp.json（VS Code 1.102+ 与 Claude Code 等外部客户端都读它；不再写 .vscode/mcp.json —— 两个文件都写会被 VS Code 读两遍，工具出现重复），默认 URL http://127.0.0.1:<ssh.localPort>/mcp（SSH 回环隧道，与 IP 无关；设置 http.host 后改为局域网直连）—— 供 VS Code 之外的客户端（Claude Code 等）使用；进程仅远端窗口自动拉起
• 工具：windows_exec(command, timeout_ms?=30000, cwd?, shell?="cmd")，支持 && 、管道等 cmd 语法；cwd 指定工作目录（不传则用服务所在目录）；shell:"gitbash" 可用 git-bash 执行 Linux 风格命令 / .sh 脚 本（自动检测本机 git-bash，未安装时明确报错）
• 文件互传：windows_fs_put(path, content|content_base64, offset?) / windows_fs_get(path, offset?, length?, as?="base64") —— 脚本/配置/固件/日志/二进制在 Linux ↔ Windows 间直传，不再受 32K 命令行上限限制；单次 ≤4MB，大文件按 offset 分块续传（put 父目录自动创建、offset=0 创建/覆盖；get 返回 eof，as:"text" 做编码探测）
• 执行增强：shell:"powershell"（pwsh 7 优先、回退 5.1）；env（{"KEY":"VAL"} 叠加环境变量）；stdin（文本喂给子进程）；windows_env 工具一次摸清 OS/工具链/串口/磁盘/代理
• 后台作业：windows_bg_start / poll / kill / list —— 长驻进程（服务器/串口监听）起任务拿 job_id，poll 增量取输出（支持 wait_ms 长轮询），kill 杀整树；完整输出落盘 bg-*.log 并随旧文件回收；服务退出时全部作业进程树一并回收
• 长命令输出实时推送（客户端带 progressToken 时；按完整行 + 限流）：0.3.9 起默认 30ms / 60000B 窗口，常见刷屏输出不再出现 跳过 N 行 标注；最终结果仍含完整输出
• 结果超 512KB 自动落盘（%TEMP%\win-exec-mcp\out-*.log），只回传尾部与日志路径；运行中超 16MB 也会改为边跑边写该文件（不丢数据）；落盘后自动回收旧文件（保留最近 20 个、并删除超过 7 天的，见 WINEXEC_SPILL_KEEP / WINEXEC_SPILL_KEEP_DAYS）
• 超时 / 客户端取消 / 断连 → 终止整棵进程树（Job Object；兜底 taskkill /T）；断连检测在静默期也生效（每 5s 主动探活），串口监听这类长命令不会因客户端被强杀而残留
• HTTP 服务默认只绑 127.0.0.1，SO_EXCLUSIVEADDRUSE 单实例：同端口第二个实例直接 bind 失败退出，不会堆叠。设置 http.host 时额外监听那个地址（0.0.0.0 = 所有网卡），内部通道始终走 127.0.0.1。每个窗口与服务之间是一条 /events SSE 长连接（实时活动推送 + 每秒心跳）：状态栏的闪电/闪烁全窗口一致，连接断开即知服务消失，无轮询。服务由订阅者决定去留：还有窗口连着就继续服务，全部断开后 2 秒自行退出；reload 时新宿主立刻重连，服务零中断。
• 环境变量：WINEXEC_PROGRESS_MS（默认 30，进度最小间隔毫秒）/ WINEXEC_PROGRESS_BYTES（默认 60000，单条进度窗口字节）/ WINEXEC_MAX_RESULT_BYTES（默认 524288，0=关闭落盘）/ WINEXEC_SPILL_KEEP（默认 20，落盘目录保留个数，0=不按个数清理）/ WINEXEC_SPILL_KEEP_DAYS（默认 7，落盘文件最长保留天数，0=不按天数清理）/ WINEXEC_PROBE_MS（默认 5000，断连探活间隔）/ WINEXEC_TOKEN（HTTP token，避免出现在命令行）/ WINEXEC_GITBASH / WINEXEC_DEBUG

固定服务路径（0.3.8+）：exe 始终从 %LOCALAPPDATA%\win-exec-mcp\bin\win-exec-mcp.exe 运行（升级时原地替换）——防火墙/安全软件按“路径”记授权，放行一次后升级不再重复弹窗、也不会被误拦。若服务连不上（端口连接超时＝被拦截）：运行命令 WinExec MCP: 修复防火墙权限（管理员）（UAC 确认后自动清除阻止规则、放行路径并清理残留进程），然后重载窗口。若机器上装有自带网络防护、且不写 Windows 防火墙规则的第三方安全软件（360、火绒、腾讯电脑管家等），一键修复可能清不掉它的拦截——请在它的信任/放行列表里加入上述固定路径（或临时退出该软件验证）。

命令

• WinExec MCP: Register user mcp.json — 重写用户级注册
• WinExec MCP: 配置服务器端 agent（SSH 转发 + 项目注册） — 一键开启 ssh.autoForward + project.autoRegister（= 首次弹窗的“完整配置”）
• WinExec MCP: 注册到本项目 / 从本项目移除注册 — 项目级 http 注册（默认 URL 走 SSH 隧道 127.0.0.1:28848；设置 http.host 后为局域网直连，供 Linux 侧/外部客户端连接）
• WinExec MCP: Start / Stop HTTP service
• WinExec MCP: 修复防火墙权限（管理员） — 清除 win-exec 的防火墙阻止规则、放行固定路径并清理残留进程（UAC 确认；完成后重载窗口）
• WinExec MCP: 诊断 — 把版本/端口/probe 结果/mcp 注册状态/ssh 转发状态一次性落到输出通道，报障贴一段就够
• WinExec MCP: 重新生成 HTTP token — 换 token 并同步全部已注册项目的 .mcp.json
• 状态栏：远端窗口显示服务状态 —— 空闲=插头 / 启动中=旋转 / 有调用=闪电 / 正在输出=闪光（服务不可用时为红底）；不显示任何数字、也不使用底色（数字会被误读成 token 消耗，而底色切换在 modern-ui 下会推动相邻状态栏项），点击出菜单（启停/诊断/复制 token/修复/注册）

设置

winExecMcp.stdio.enabled / winExecMcp.http.enabled / winExecMcp.http.port / winExecMcp.http.token（留空自动生成）/ winExecMcp.ssh.localPort

English

Self-contained extension (bundled exe + full C source code) that lets AI agents running on the Remote-SSH (Linux) side (Copilot, Claude Code, …) execute commands on the Windows client — any CLI, script, or Windows-specific tool (including serial-port/hardware utilities) — and get stdout/stderr/exit code back immediately over the existing SSH channel.

UI text follows the VS Code display language (English / Simplified Chinese); no manual switch needed.

Install and go

code --install-extension win-exec-mcp-0.6.12.vsix

→ Reload Window → pick one of the two scopes in the consent dialog:

• Full setup (incl. server-side agent): besides the VS Code built-in agent, it also appends the SSH RemoteForward to ~/.ssh/config (backed up first) and writes the project-root .mcp.json (with the Bearer token; VS Code and Claude Code / Cursor all read this single file, so no duplicate registration) — server-side Claude Code / Cursor etc. work right away, no manual editing.
• VS Code only: only registers the user-level mcp.json and starts/connects the local HTTP service; the external agent part can be added later at any time with a command (it is never enabled automatically).

Consent once, then fully automatic: once you picked 同意/完整配置 (including consent given in older versions), remote windows auto-maintain the SSH RemoteForward and the project registration (URL/token): missing entries are added, stale ones rewritten, and you only get a "configuration files repaired; reload the window" notice. If no project is open, project registration happens automatically once you open one. Picking VS Code only or Not now keeps the external part off; re-run WinExec MCP: Enable / Re-run setup (consent) to change your mind. Troubleshooting logs live in Output → WinExec MCP.

Declining (Not now) writes no files and starts no process; you can enable it later with WinExec MCP: Enable / Re-run setup (consent) or Register user mcp.json.

Explicit consent first

The extension only modifies files after you answer the consent dialog. Once authorized (including consent given in older versions) it auto-enables and repairs that setup (RemoteForward + project registration incl. token) on every remote window start, and only asks for a window reload when files were fixed; VS Code only keeps the external part off.

What this extension may modify (only after you consent, all opt-out)

Security model

• The HTTP service binds to 127.0.0.1 by default and requires a Bearer token (auto-generated random token, persisted only in VS Code global storage; configurable via winExecMcp.http.token)
• The bundled win-exec-mcp.exe is fully open source in this package (src/win-exec-mcp.c) — build it yourself with mingw if you prefer
• No telemetry, no network calls other than the localhost MCP traffic

Dual MCP modes

• stdio (win-exec-mcp): registered in the user-level mcp.json (location: local); the Windows client spawns the process and it is reached over the Remote-SSH channel — this is what the VS Code built-in agent uses. Not registered in Remote-SSH windows (the http entry already covers the built-in agent; keeping both duplicates the tools); WSL / local windows are unaffected.
• http: registered in the project root .mcp.json (read by VS Code 1.102+ and external clients alike; .vscode/mcp.json is no longer written — writing both made VS Code see the server twice, duplicating the tools); default URL http://127.0.0.1:<ssh.localPort>/mcp (SSH loopback tunnel, independent of LAN IPs; set http.host for direct LAN access) — for clients outside VS Code (Claude Code etc.). The process is auto-started only in remote windows.
• Tool: windows_exec(command, timeout_ms?=30000, cwd?, shell?="cmd") — cmd syntax including && and pipes; cwd sets the working directory (defaults to the service's own directory); shell:"gitbash" runs Linux-style commands / .sh scripts through git-bash (auto-detected; a clear error is reported when git-bash is not installed).
• File transfer: windows_fs_put(path, content|content_base64, offset?) / windows_fs_get(path, offset?, length?, as?="base64") — move scripts/configs/firmware/logs/binaries between Linux ↔ Windows directly, free of the 32K command-line limit; ≤4MB per call, larger files chunked via offset (put auto-creates parent dirs and offset=0 creates/overwrites; get reports eof; as:"text" applies encoding detection).
• Exec enhancements: shell:"powershell" (pwsh 7 preferred, falls back to 5.1); env ({"KEY":"VAL"} overlay); stdin (text fed to the child); windows_env tool for a one-shot OS/toolchain/COM/disks/proxy overview.
• Background jobs: windows_bg_start / poll / kill / list — launch long-running processes (servers, serial monitors), poll incremental output (with wait_ms long-poll), kill the whole tree; full output spilled to bg-*.log (reclaimed with old spill files); all job trees are reclaimed when the service exits.
• Live output: long-running commands stream line-aligned, rate-limited progress (30 ms / 60000 bytes by default since 0.3.9), so typical output no longer shows skipped N lines markers; the final result still carries the full output.
• Large results: outputs over 512KB are spilled to %TEMP%\win-exec-mcp\out-*.log; the tool result returns the tail plus the log path, and old spill files are reclaimed automatically (keep the newest 20, drop anything older than 7 days — WINEXEC_SPILL_KEEP / WINEXEC_SPILL_KEEP_DAYS). Output that exceeds 16MB while running is streamed into that file as it arrives — nothing is dropped.
• Timeout, client cancellation or disconnect terminate the whole process tree (Job Object, taskkill /T fallback); disconnect detection also works during silent periods (a liveness probe every 5s), so a long-running command is not left behind when the client is force-killed.
• The HTTP service binds 127.0.0.1 by default and uses SO_EXCLUSIVEADDRUSE: a second instance on the same port fails to bind and exits instead of piling up. Setting http.host additionally listens on that address (0.0.0.0 = all NICs); the internal channel always uses 127.0.0.1. Each window holds one /events SSE connection to the service (live activity push plus a 1s heartbeat): the status-bar zap/flicker is identical in every window, a dropped connection means the service is gone, and there is no polling. The service lives while subscribers exist and exits 2s after the last one disconnects; a reloaded window reconnects immediately, so the service never blinks and never lingers as an orphan.
• Environment variables: WINEXEC_PROGRESS_MS (default 30) / WINEXEC_PROGRESS_BYTES (default 60000) / WINEXEC_MAX_RESULT_BYTES (default 524288, 0 disables spilling) / WINEXEC_SPILL_KEEP (default 20) / WINEXEC_SPILL_KEEP_DAYS (default 7) / WINEXEC_PROBE_MS (default 5000, liveness probe interval) / WINEXEC_TOKEN (HTTP token, kept out of the command line) / WINEXEC_GITBASH / WINEXEC_DEBUG.

Stable service path (0.3.8+). The exe always runs from %LOCALAPPDATA%\win-exec-mcp\bin\win-exec-mcp.exe (replaced in place on upgrades) — Windows Firewall and security suites remember network permissions per path, so a single allow survives upgrades and is never silently blocked. If the service becomes unreachable (a connection timeout means it is being blocked), run WinExec MCP: Fix firewall permissions (administrator) (it clears block rules, allows the stable path and kills leftovers after UAC confirmation), then reload the window. If a third-party security suite (360, Huorong, Tencent PC Manager, …) enforces its own network filter instead of Windows Firewall rules, add the stable path above to its trust/allow list (or exit it temporarily to verify).

Commands

• WinExec MCP: Register user mcp.json — rewrite the user-level registration
• WinExec MCP: Configure server-side agent (SSH forwarding + project registration) — one-click enable (equals the "Full setup" consent choice)
• WinExec MCP: Register in this project / Remove from this project — project-level http registration (SSH-tunnel URL 127.0.0.1:28848 by default; direct LAN when http.host is set, for clients on the Linux side)
• WinExec MCP: Start / Stop HTTP service
• WinExec MCP: Fix firewall permissions (administrator) — clears win-exec firewall block rules, allows the stable path and kills leftover processes (UAC confirmation; reload afterwards)
• WinExec MCP: Diagnostics — dumps version/port/probe results/mcp registrations/ssh forward status into the output channel in one shot
• WinExec MCP: Regenerate HTTP token — rotates the token and resyncs all registered projects' .mcp.json
• Status bar: the remote window shows service state - plug=idle / sync=starting / bolt=a tool call is in flight / sparkle=output is arriving (red background when the service is down). Deliberately no numbers (they read as token usage) and no background colour (switching it shifts neighbouring status bar items in modern-ui). Click for a menu (start/stop, diagnostics, token copy, repair, registration)

Settings

winExecMcp.stdio.enabled / winExecMcp.http.enabled / winExecMcp.http.port / winExecMcp.http.token (auto-generated when empty) / winExecMcp.ssh.localPort