pwsh-exec-mcp

pwsh-exec

Windows 向けの最小限で透明性の高い PowerShell 7 MCP です。ツールは 1 つで、コマンドを実行し、生の終了コード／stdout／stderr を返します。

pwsh-exec は、Windows 向けの最小限で透明性の高い PowerShell 7 MCP サーバーです。run_command という単一のツールを公開し、新しい pwsh プロセスでコマンドを実行して、生の exit_code、stdout、stderr を返します。解析、フィルタリング、再フォーマットは一切行いません。

• ツールは 1 つ、入力は 3 つ — command、timeout（秒）、任意の working_directory。
• 透明性 — 終了コードと stdout、stderr を、エラーも含めてそのまま返します。
• ステートレス — 呼び出しごとに新しいプロセスが起動し、セッション状態は保持されません。
• 上限付き — 呼び出しごとのタイムアウトは 1～300 秒です。タイムアウト時にはプロセスツリー全体を終了します。
• Windows 向けに強化 — ロケールを問わず UTF-8 で出力し、PATH はレジストリから毎回読み込み、stdin によるハングを防ぎます。
• 対象外 — 永続的なシェル、管理者権限が必要なタスク、長時間実行またはバックグラウンドのジョブには対応しません。

Windows 上のあらゆる AI エージェントに本物のターミナルを提供します。コマンドを送信すると、ターミナルが出力した内容をそのまま受け取れます。

ステータス — 安定・完成

機能が揃っており、安定しています。ツールは 1 つで、API は v1.0.0 で固定済み、38 件のテストに合格しており、既知のバグもなく 2026 年 4 月から実際のエージェント作業で日常的に使用されています。再現可能なバグは修正しますが、意図的に範囲を小さく保ち、1 つの機能に徹しています。

必要条件

• Windows
• PowerShell 7（pwsh）が PATH にあること — これは最新のクロスプラットフォーム版 PowerShell であり、組み込みの Windows PowerShell 5.1（powershell.exe）ではありません。winget install Microsoft.PowerShell を使うか、公式のインストールガイドからインストールしてください。
• uv — 以下で使用する uvx ランナーを提供します。

インストール

クローンは不要です。uvx が必要に応じて取得し、実行します。MCP クライアントに登録してください（stdio トランスポート）。

あらゆる 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 アプリである Claude Desktop には独自のコンソールがなく、コンソールプログラムを直接起動すると、子プロセス（pwsh → git やその他の外部 .exe）で正常なコンソールが使えないことがあります。その結果、ウィンドウのちらつき、stdout の欠落、PATH の検索失敗が発生する可能性があります。cmd.exe が先に非表示のコンソールを取得し、すべての子プロセスがそれを継承します。これは Desktop Commander をはじめとする他の Windows MCP サーバーでも使われている方法です。

ツール：run_command

パラメーター	型	必須	説明
command	文字列	はい	実行する PowerShell コマンドまたはスクリプトです。
timeout	整数	はい	タイムアウト（秒単位。ミリ秒ではありません）。1～300。
working_directory	文字列	いいえ	絶対パスです。既定値は解決済みの作業ディレクトリです（設定を参照）。

出力はプレーンテキストです。最初に終了コードが表示され、その後にラベル付きの stdout セクションと stderr セクションが続きます（空の場合も表示されるため、2 つのストリームを混同することはありません）。最後に、タイムスタンプと経過時間を含む診断フッターが表示されます。

たとえば、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 行だけを残して切り詰めるため、コンテキストウィンドウが出力で埋め尽くされることはありません。

Windows で堅牢に動作する理由

ホストプロセスから Windows 上でシェルを実行する際には、細かな落とし穴が数多くあります。pwsh-exec がそれらに対処するため、エージェントが気にする必要はありません。

• あらゆるロケールで 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 を渡すか、依存する手順を 1 つのコマンドにまとめてください。
• 管理者権限が必要なタスク — ホストユーザーとして実行され、権限昇格は行いません。
• 長時間実行／バックグラウンドジョブ — 上限は 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