{
  "markdown": "# powershell-mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents real, **non-intrusive** access to Windows PowerShell.\n\nMost tools that let an agent run Windows commands spawn a visible console window for every call — which steals focus and interrupts whatever you're typing. `powershell-mcp` runs everything in a **hidden process** (`windowsHide: true` / no `CreateWindow`), captures structured output, enforces hard timeouts, and exposes purpose-built tools for service and system management. Built for running unattended next to a human at the keyboard.\n\n## Why\n\n- **No popup windows.** Commands run hidden; your foreground app keeps focus.\n- **Structured + safe.** Every call returns `{ stdout, stderr, exit_code, duration, timed_out }`. Hard timeout with tree-kill. Output is capped so a runaway command can't flood the context.\n- **Real Windows management.** First-class tools for services and system info, not just a raw shell — handy for managing Windows servers and backup systems.\n- **Cross-shell.** Prefers `pwsh` (PowerShell 7+) and falls back to `powershell.exe`; override with `PWSH_MCP_EXE`.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_powershell` | Run any PowerShell script/command (hidden). `{ script, cwd?, timeoutMs? }` |\n| `run_program` | Run a **native executable directly** (no shell) and capture clean stdout/stderr + exit code - for `gh`/`git`/`docker`/`node` and other console binaries whose output a hidden shell swallows. `{ program, args?, cwd?, timeoutMs? }` |\n| `list_services` | List services, optional `filter` wildcard. |\n| `get_service` | Detailed status of one service by name. |\n| `control_service` | `start` / `stop` / `restart` / `status` a service. |\n| `system_info` | OS, CPU, memory, and per-drive disk summary. |\n| `ssh_exec` | Run a command on a remote host over SSH, **fully in-process** (no `ssh.exe`, no WSL — works headless). `{ host, username, command, port?, privateKeyPath?, passphrase?, password?, timeoutMs? }` |\n| `winrm_exec` | Run a command on a remote **Windows** host via PowerShell Remoting (WinRM / `Invoke-Command`). No SSH server or agent needed on the target. `{ computerName, command, username?, password?, useSsl?, authentication?, timeoutMs? }` |\n| `sftp_upload` | Upload a local file to a remote host over SFTP, in-process (ssh2 — no scp.exe/WSL, headless). `{ localPath, remotePath, host, username, port?, privateKeyPath?, passphrase?, password?, timeoutMs? }` |\n| `sftp_download` | Download a remote file to this host over SFTP, in-process. Same params as `sftp_upload`. |\n\n> **Native programs:** Windows PowerShell routes a native command's stdout to the console, so run hidden it is lost. Use `run_program` (direct-exec) for console binaries like `gh`/`git`/`docker`; use `run_powershell` for PowerShell/cmdlet logic.\n\n## See it work\n\nReal calls, real output — headless, no console window, structured results:\n\n```text\n# ssh_exec — run a command on a Linux box, in-process (no ssh.exe, no WSL)\n> ssh_exec  host=192.168.0.5  username=isak  command=\"uptime; systemctl is-active app\"\n$ ssh isak@192.168.0.5  (exit=0, 818ms)\n 2 days, 23:53,  load average: 0.00, 0.01, 0.04\nactive\n\n# sftp_upload — deploy a file, in-process (no scp.exe)\n> sftp_upload  localPath=C:\\deploy\\app.py  remotePath=/home/isak/app.py  host=192.168.0.5 ...\nsftp upload: C:\\deploy\\app.py → isak@192.168.0.5:/home/isak/app.py\nOK (9129 bytes, 714ms)\n```\n\n## Remote operations\n\n`powershell-mcp` manages more than the local box. Windows' own `ssh.exe` produces no capturable output when run from a windowless/background process, and shipping WSL to every server doesn't scale — so remote exec is built in:\n\n- **`ssh_exec`** uses the pure-JS [`ssh2`](https://github.com/mscdex/ssh2) client (no external binary), so it works headless and needs nothing on the target beyond an SSH server. Ideal for Linux hosts.\n- **`winrm_exec`** uses native PowerShell Remoting, so a Windows fleet needs only WinRM enabled — no per-server install.\n\n## Telemetry (anonymous, opt-out)\n\nOn startup the server sends a one-time ping (host id, version, OS, timestamp) and flushes per-tool call **counts** every 30 minutes (and on exit). This helps prioritise which tools matter. **No command content, arguments, output, or paths are ever sent.**\n\n- Disable entirely: set `POWERSHELL_MCP_NO_TELEMETRY=1`.\n- Override the endpoint: set `POWERSHELL_MCP_TELEMETRY_URL`.\n\nThe collector under [`collector/`](collector/) is a standalone Node.js service (JSONL append, systemd unit, nginx snippet, `deploy.sh`) deployed separately.\n\n## Install\n\nThe canonical npm package is [**`@imrrd/powershell-mcp`**](https://www.npmjs.com/package/@imrrd/powershell-mcp).\n\nRun it directly from npm in an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"powershell\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@imrrd/powershell-mcp@latest\"]\n    }\n  }\n}\n```\n\nOr install the CLI globally:\n\n```bash\nnpm install -g @imrrd/powershell-mcp\n```\n\n> **Migrating:** `powershell-mcp` is deprecated and will not receive a patched legacy release. Remove it and install `@imrrd/powershell-mcp@0.5.3` or later.\n\nFor development from source:\n\n```bash\nnpm install\nnpm run build\n```\n\nSee [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) for the canonical package-based client configuration.\n\n## Develop\n\n```bash\nnpm run dev        # run from source (tsx)\nnpm test           # unit + (where a shell is present) integration tests\nnpm run typecheck\n```\n\nCI runs build + tests on both `windows-latest` and `ubuntu-latest`.\n\n## Security notes\n\n- `winrm_exec` sends caller-controlled connection details to the local PowerShell child over stdin; credentials are not placed in process arguments or environment variables.\n- `control_service` and many commands require the MCP host process to run with sufficient privileges.\n- The server runs whatever script it's given — run it only in environments you trust, behind a host (like Claude) that you control. A future release will add an optional allow/deny policy and confirmation gating.\n\n## License\n\nMIT © IMR Research & Development (UK)\n\n",
  "bytes": 6162,
  "sha": "489fb0f2499c2e50dd2b7b89c087480a405c6d559a9a9e57f75695a72d9f0a11",
  "repo_slug": "imrrd/powershell-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_imrrd_powershell_mcp_c66cae0d/readme"
}