powershell-mcp

powershell-mcp

AI エージェントに Windows PowerShell への実用的で非侵入型のアクセスを提供するModel Context Protocolサーバーです。

エージェントが Windows コマンドを実行できるようにするツールの多くは、呼び出しのたびに表示されるコンソールウィンドウを起動します。そのためフォーカスが奪われ、入力中の作業が中断されます。powershell-mcp はすべての処理を非表示のプロセス（windowsHide: true / CreateWindow なし）で実行し、構造化された出力を取得して、厳格なタイムアウトを適用します。また、サービスやシステム管理に特化したツールを提供します。キーボードを使う人の隣で、無人で実行するために作られています。

理由

• ポップアップウィンドウが表示されません。 コマンドは非表示で実行されるため、フォアグラウンドのアプリはフォーカスを維持できます。
• 構造化され、安全です。 すべての呼び出しは { stdout, stderr, exit_code, duration, timed_out } を返します。プロセスツリーの強制終了を伴う厳格なタイムアウトを設定しています。暴走したコマンドがコンテキストをあふれさせないよう、出力には上限があります。
• Windows を本格的に管理できます。 生のシェルだけでなく、サービスやシステム情報を扱う専用ツールを備えています。Windows サーバーやバックアップシステムの管理に便利です。
• 複数のシェルに対応します。 pwsh（PowerShell 7 以降）を優先し、利用できない場合は powershell.exe にフォールバックします。PWSH_MCP_EXE で上書きできます。

ツール

ツール	説明
run_powershell	任意の PowerShell スクリプト／コマンドを実行します（非表示）。{ script, cwd?, timeoutMs? }
run_program	ネイティブ実行可能ファイルを直接実行し（シェルなし）、クリーンな stdout/stderr と終了コードを取得します。隠しシェルでは出力が失われる gh／git／docker／node などのコンソールバイナリに使用します。{ program, args?, cwd?, timeoutMs? }
list_services	サービスを一覧表示します。任意で filter ワイルドカードを指定できます。
get_service	名前を指定して、1 つのサービスの詳細な状態を取得します。
control_service	サービスの start／stop／restart／status を実行します。
system_info	OS、CPU、メモリ、ドライブごとのディスク概要を取得します。
ssh_exec	SSH 経由でリモートホスト上のコマンドを実行します。完全にプロセス内で動作するため（ssh.exe も WSL も不要）、ヘッドレス環境で動作します。{ host, username, command, port?, privateKeyPath?, passphrase?, password?, timeoutMs? }
winrm_exec	PowerShell リモート処理（WinRM／Invoke-Command）経由でリモートのWindowsホスト上のコマンドを実行します。ターゲットに SSH サーバーやエージェントは不要です。{ computerName, command, username?, password?, useSsl?, authentication?, timeoutMs? }
sftp_upload	SFTP 経由でローカルファイルをリモートホストにアップロードします。プロセス内で動作するため（ssh2、scp.exe／WSL なし）、ヘッドレス環境で実行できます。{ localPath, remotePath, host, username, port?, privateKeyPath?, passphrase?, password?, timeoutMs? }
sftp_download	SFTP 経由でリモートファイルをこのホストにダウンロードします。パラメーターは sftp_upload と同じです。

ネイティブプログラム： Windows PowerShell は、ネイティブコマンドの stdout をコンソールに出力するため、非表示で実行すると出力が失われます。gh／git／docker などのコンソールバイナリには run_program（直接実行）を使用し、PowerShell／コマンドレットのロジックには run_powershell を使用してください。

動作例

実際の呼び出しと実際の出力を紹介します。ヘッドレスで、コンソールウィンドウを表示せず、構造化された結果を返します。

# ssh_exec — run a command on a Linux box, in-process (no ssh.exe, no WSL)
> ssh_exec  host=192.168.0.5  username=isak  command="uptime; systemctl is-active app"
$ ssh [email protected]  (exit=0, 818ms)
 2 days, 23:53,  load average: 0.00, 0.01, 0.04
active

# sftp_upload — deploy a file, in-process (no scp.exe)
> sftp_upload  localPath=C:\deploy\app.py  remotePath=/home/isak/app.py  host=192.168.0.5 ...
sftp upload: C:\deploy\app.py → [email protected]:/home/isak/app.py
OK (9129 bytes, 714ms)

リモート操作

powershell-mcp はローカルマシン以外も管理します。Windows 標準の ssh.exe は、ウィンドウのないバックグラウンドプロセスから実行すると取得可能な出力を生成しません。また、すべてのサーバーに WSL を導入する方法は拡張性に欠けるため、リモート実行機能を組み込んでいます。

• ssh_exec は純粋な JavaScript の ssh2 クライアント（外部バイナリ不要）を使用するため、ヘッドレス環境で動作します。ターゲットに必要なのは SSH サーバーだけです。Linux ホストに最適です。
• winrm_exec はネイティブの PowerShell リモート処理を使用するため、Windows 環境では WinRM を有効にするだけで利用できます。サーバーごとのインストールは不要です。

テレメトリー（匿名、オプトアウト方式）

起動時にサーバーは一度だけ ping（ホスト ID、バージョン、OS、タイムスタンプ）を送信し、ツールごとの呼び出し回数を30分ごと（および終了時）に送信します。これにより、重要なツールを優先できます。コマンドの内容、引数、出力、パスは一切送信されません。

• 完全に無効にするには、POWERSHELL_MCP_NO_TELEMETRY=1 を設定します。
• エンドポイントを上書きするには、POWERSHELL_MCP_TELEMETRY_URL を設定します。

collector/ にあるコレクターは、別途デプロイするスタンドアロンの Node.js サービスです（JSONL 追記、systemd ユニット、nginx スニペット、deploy.sh）。

インストール

正式な npm パッケージは @imrrd/powershell-mcp です。

MCP クライアントから npm 経由で直接実行します。

{
  "mcpServers": {
    "powershell": {
      "command": "npx",
      "args": ["-y", "@imrrd/powershell-mcp@latest"]
    }
  }
}

または、CLI をグローバルにインストールします。

npm install -g @imrrd/powershell-mcp

移行について： powershell-mcp は非推奨であり、旧バージョン向けの修正リリースは提供されません。削除して、@imrrd/[email protected] 以降をインストールしてください。

ソースから開発する場合：

npm install
npm run build

正式なパッケージベースのクライアント設定については、examples/claude_desktop_config.json を参照してください。

開発

npm run dev        # run from source (tsx)
npm test           # unit + (where a shell is present) integration tests
npm run typecheck

CI では windows-latest と ubuntu-latest の両方でビルドとテストを実行します。

セキュリティに関する注意事項

• winrm_exec は、呼び出し元が指定した接続情報を stdin 経由でローカルの PowerShell 子プロセスに送信します。認証情報がプロセス引数や環境変数に含まれることはありません。
• control_service と多くのコマンドを実行するには、MCP ホストプロセスに十分な権限が必要です。
• サーバーは渡されたスクリプトをそのまま実行します。信頼できる環境でのみ、制御下にあるホスト（Claude など）を介して実行してください。今後のリリースでは、任意で設定できる許可／拒否ポリシーと確認による制御を追加する予定です。

ライセンス

MIT © IMR Research & Development (UK)