Metadata-Version: 2.4
Name: pwsh-exec
Version: 1.0.1
Summary: A minimal, transparent PowerShell 7 MCP for Windows — one tool: run a command, get raw exit code / stdout / stderr back.
Project-URL: Homepage, https://github.com/Jason26214/pwsh-exec-mcp
Project-URL: Repository, https://github.com/Jason26214/pwsh-exec-mcp
Project-URL: Issues, https://github.com/Jason26214/pwsh-exec-mcp/issues
Author: Jason26214
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,claude,cli,command-execution,mcp,model-context-protocol,powershell,pwsh,shell,windows
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.1.0
Description-Content-Type: text/markdown

# pwsh-exec

![version](https://img.shields.io/badge/version-1.0.0-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![python](https://img.shields.io/badge/python-3.11%2B-blue)
![platform](https://img.shields.io/badge/platform-Windows-blue)
![PowerShell](https://img.shields.io/badge/PowerShell-7-5391FE)

> 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](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows).
- **[uv](https://docs.astral.sh/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:

```bash
uvx pwsh-exec
```

### Claude Desktop

Edit `claude_desktop_config.json`:

```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 `.exe`s) 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](#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:

```json
{
  "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](LICENSE) © 2026 Jason26214

<!-- mcp-name: io.github.Jason26214/pwsh-exec-mcp -->

