pwsh-exec-mcp

pwsh-exec

面向 Windows 的精简、透明的 PowerShell 7 MCP 服务——只有一个工具：运行命令，并返回原始退出代码、stdout 和 stderr。

pwsh-exec 是一个面向 Windows 的精简、透明的 PowerShell 7 MCP 服务。它提供单个工具 run_command，在全新的 pwsh 进程中运行命令，并返回原始的 exit_code、stdout 和 stderr——不解析、不筛选、不重新格式化。

• 一个工具，三个输入——command、timeout（秒）和可选的 working_directory。
• 透明——原样返回退出代码、stdout 和 stderr，包括错误。
• 无状态——每次调用都会启动新进程；不会保留会话状态。
• 有界——每次调用的超时为 1–300 秒；超时后会终止整个进程树。
• 针对 Windows 加固——任何区域设置下均以 UTF-8 输出，从注册表中重新读取 PATH，不会因 stdin 卡住。
• 不适用于——持久 Shell、需要管理员权限的任务，或长时间运行的后台任务。

它为 Windows 上的任何 AI Agent 提供真正的终端：发送命令，即可获得终端原样生成的内容。

状态 — 稳定且完整

功能完整且稳定。只有一个工具，API 已冻结为 v1.0.0，38 项测试全部通过；自 2026 年 4 月起，每天都在用于驱动实际 Agent 工作，暂无已知 Bug。可复现的 Bug 会得到修复；项目范围有意保持精简——只做一件事。

要求

• Windows
• PowerShell 7（pwsh）已加入 PATH——这是现代跨平台版 PowerShell，不是内置的 Windows PowerShell 5.1（powershell.exe）。可通过 winget install Microsoft.PowerShell 安装，或参阅官方安装指南。
• uv——提供下文使用的 uvx 运行器。

安装

无需克隆——uvx 会按需获取并运行。使用 stdio 传输将其注册到 MCP 客户端：

任何 MCP 客户端

将以下内容用作服务的启动命令：

uvx pwsh-exec

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "pwsh-exec": {
      "command": "cmd",
      "args": ["/c", "uvx", "pwsh-exec"]
    }
  }
}

建议在 Claude Desktop 中使用 cmd /c 包装器：作为 Electron 应用，它没有自己的控制台，直接启动控制台程序可能导致子进程（pwsh → git 和其他外部 .exe）无法正常使用控制台，出现窗口闪烁、stdout 丢失、PATH 查找失败等问题。cmd.exe 会先获取隐藏控制台，之后每个子进程都会继承它。Desktop Commander 和其他 Windows MCP 服务也采用了相同的做法。

工具：run_command

参数	类型	必填	描述
command	string	是	要运行的 PowerShell 命令或脚本。
timeout	integer	是	超时时间，以秒为单位（不是毫秒）。1–300。
working_directory	string	否	绝对路径。默认为解析后的工作目录（见配置）。

输出为纯文本：首先是退出代码，接着是带标签的 stdout 和 stderr 部分（即使内容为空也会显示，因此两个流不会混淆），最后是包含时间戳和耗时的诊断页脚。

例如，使用 command: "git status" 调用 run_command，会返回未经修改的原始 git 输出：

exit_code: 0

stdout:
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   app.py

no changes added to commit (use "git add" and/or "git commit -a")

stderr:
(empty)

[2026-06-13 08:43:11 | 625ms]

不会对任何内容进行摘要或筛选。非零退出代码、写入 stderr 的语法错误、空结果——都会如终端生成时那样返回。每个流中超过 500 行的输出会截取前 250 行和后 250 行，避免内容淹没上下文窗口。

为什么它在 Windows 上健壮可靠

从宿主进程在 Windows 上运行 shell 有许多容易踩的小坑。pwsh-exec 会处理这些问题，无需 Agent 操心：

• 任何区域设置下均使用 UTF-8 — 输出编码全程强制为 UTF-8，因此即使在非英语 Windows 上，文本也不会乱码。它在 zh-CN / GBK 系统上经过加固，这些系统最容易遇到编码问题；此修复具有普适性。
• 始终获取最新的 PATH — 每次调用都会从注册表读取用户范围的环境变量，因此即使在宿主启动后才安装的 CLI 也能找到（并且会正确展开 %USERPROFILE%\... 这类 REG_EXPAND_SZ 值）。
• 干净地终止进程树 — 超时后会终止整个进程树（pwsh 及其启动的任何子进程，例如 node、python），不会留下孤儿进程。
• 不会因 stdin 卡住 — stdin 会断开连接，因此会探测 stdin 的工具（git 和其他 MSYS2 程序）不会死锁。
• 合理截断输出 — 超长输出会保留开头和结尾，而不会撑爆模型的上下文。

不适用场景

小而精的范围正是其设计所在。pwsh-exec 刻意不提供以下功能：

• 持久会话 — 每次调用都是无状态的；cd 和变量不会沿用。请传入 working_directory，或将相互依赖的步骤合并到一条命令中。
• 管理员提权任务 — 它以宿主用户身份运行，不会提权。
• 长时间运行／后台任务 — 硬性上限为 300 s，且调用为同步方式。安装程序、大型构建、开发服务器和文件监视器均不在适用范围内。

配置

working_directory 默认使用一个解析后的目录，按以下顺序选择（优先级从高到低）：

1. 调用时传入的 working_directory 参数。
2. 已设置时使用 PWSH_EXEC_DEFAULT_DIR 环境变量。
3. 内置回退路径：%TEMP%\pwsh-exec。

要更改默认值，请在 MCP 客户端的配置中设置 PWSH_EXEC_DEFAULT_DIR：

{
  "mcpServers": {
    "pwsh-exec": {
      "command": "cmd",
      "args": ["/c", "uvx", "pwsh-exec"],
      "env": { "PWSH_EXEC_DEFAULT_DIR": "D:\\scratch" }
    }
  }
}

未设置或为空时，将回退到内置默认值。默认目录位于 %TEMP% 下（使用独立子文件夹，因此可以整体清理），而不是将文件散落到共享临时目录中。

许可证

MIT © 2026 Jason26214