io.github.Jason26214/pwsh-exec-mcp

pwsh-exec

A minimal, transparent PowerShell 7 MCP for Windows — one tool: run a command, get raw exit code / stdout / stderr back.

pwsh-exec is a minimal, transparent PowerShell 7 MCP server for Windows. It exposes a single tool, run_command, that runs a command in a fresh pwsh process and returns the raw exit_code, stdout, and stderr — nothing parsed, filtered, or reformatted.

• One tool, three inputs — command, timeout (seconds), optional working_directory.
• Transparent — exit code + stdout + stderr returned verbatim, errors and all.
• Stateless — every call is a new process; no session state persists.
• Bounded — 1–300 s timeout per call; on timeout the whole process tree is killed.
• Windows-hardened — UTF-8 output on any locale, PATH read fresh from the registry, no stdin hangs.
• Not for — persistent shells, admin-elevated tasks, or long-running / background jobs.

It gives any AI agent on Windows a real terminal: you send a command, you get back exactly what the terminal produced.

Status — stable & complete

Feature-complete and stable. One tool, a frozen v1.0.0 API, 38 passing tests, in daily use driving real agent work since April 2026 with no known bugs. Reproducible bugs get fixed; the scope stays intentionally small — it does one thing.

Requirements

• Windows
• PowerShell 7 (pwsh) on PATH — this is the modern cross-platform PowerShell, not the built-in Windows PowerShell 5.1 (powershell.exe). Install it via winget install Microsoft.PowerShell or from the official install guide.
• uv — provides the uvx runner used below.

Install

No clone required — uvx fetches and runs it on demand. Register it with your MCP client (stdio transport):

Any MCP client

Use this as the server's launch command:

uvx pwsh-exec

Claude Desktop

Edit claude_desktop_config.json:

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

The cmd /c wrapper is recommended on Claude Desktop: as an Electron app it has no console of its own, and launching a console program directly can leave child processes (pwsh → git and other external .exes) without a working console — flickering windows, lost stdout, PATH lookups failing. cmd.exe acquires the hidden console first and every child inherits it. This is the same pattern Desktop Commander and other Windows MCP servers use.

The tool: run_command

Parameter	Type	Required	Description
command	string	yes	The PowerShell command or script to run.
timeout	integer	yes	Timeout in seconds (not milliseconds). 1–300.
working_directory	string	no	Absolute path. Defaults to the resolved working directory (see Configuration).

The output is plain text: the exit code first, then labelled stdout and stderr sections (empty ones still show, so the two streams are never ambiguous), then a diagnostic footer with a timestamp and elapsed time.

For example, calling run_command with command: "git status" returns the raw git output, untouched:

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]

Nothing is summarised or filtered. A non-zero exit code, a syntax error written to stderr, an empty result — all of it comes back as the terminal produced it. Output longer than 500 lines per stream is trimmed to the first and last 250 lines so it never floods the context window.

Why it's robust on Windows

Running a shell on Windows from a host process is full of small traps. pwsh-exec handles them so the agent doesn't have to:

• UTF-8 on any locale — output encoding is forced to UTF-8 end to end, so text isn't mangled even on non-English Windows. It was hardened on zh-CN / GBK systems, where these encoding bugs bite hardest; the fix is universal.
• Always-fresh PATH — User-scope environment variables are read from the registry on every call, so CLIs you installed after the host started are still found (and REG_EXPAND_SZ values like %USERPROFILE%\... are expanded correctly).
• Clean process-tree kills — on timeout the whole tree is terminated (pwsh plus any children it spawned, e.g. node, python), leaving no orphans.
• No stdin hangs — stdin is detached, so tools that probe it (git and other MSYS2 programs) don't deadlock.
• Sane truncation — very long output is head+tail trimmed instead of blowing up the model's context.

What it's not for

The small scope is the design. pwsh-exec deliberately does not do:

• Persistent sessions — each call is stateless; cd and variables don't carry over. Pass working_directory, or combine dependent steps into one command.
• Admin-elevated tasks — it runs as the host user, with no elevation.
• Long-running / background jobs — the hard cap is 300 s and calls are synchronous. Installers, large builds, dev servers, and watchers are out of scope.

Configuration

working_directory defaults to a resolved directory, chosen in this order (highest priority first):

1. The working_directory argument passed on the call.
2. The PWSH_EXEC_DEFAULT_DIR environment variable, if set.
3. The built-in fallback: %TEMP%\pwsh-exec.

To change the default, set PWSH_EXEC_DEFAULT_DIR in your MCP client's config:

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

An unset or blank value falls back to the built-in default. The default lives under %TEMP% (its own subfolder, so you can wipe it wholesale) rather than scattering files into the shared temp directory.

License

MIT © 2026 Jason26214