# powershell MCP server

> Provides AI agents with headless Windows management capabilities via PowerShell, SSH, WinRM, and SFTP.

- Repository: https://github.com/IMRRD/powershell-mcp
- Page: https://hostedmcp.org/servers/imrrd/powershell-mcp
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.9.1

## Install

### Claude Code

```sh
claude mcp add powershell-mcp -- npx -y @imrrd/powershell-mcp
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "powershell-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@imrrd/powershell-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"powershell-mcp","type":"stdio","command":"npx","args":["-y","@imrrd/powershell-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add powershell-mcp -- npx -y @imrrd/powershell-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.powershell-mcp]
command = "npx"
args = ["-y", "@imrrd/powershell-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user powershell-mcp npx -- -y @imrrd/powershell-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Tools (20)

- `run_powershell`: Run a PowerShell script/command on this Windows host in a hidden process (no console window appears). Returns stdout, stderr and exit code. Use for any Windows command, file, or system task.
- `list_services`: List Windows services, optionally filtered by a name pattern. Returns Name, DisplayName, Status.
- `get_service`: Get detailed status of one Windows service by name.
- `control_service`: Start, stop, or restart a Windows service (requires the MCP host process to have sufficient privileges).
- `system_info`: Return OS, CPU, memory and disk summary for this Windows host.
- `ssh_exec`: Run a command on a remote host over SSH, fully in-process (no ssh.exe, no WSL â€” works headless). Use for Linux hosts or any OpenSSH target. Auth via privateKeyPath or password. Returns stdout, stderr, exit code.
- `winrm_exec`: Run a command on a remote Windows host via PowerShell Remoting (WinRM / Invoke-Command). Native to Windows Server â€” no SSH server or agent needed on the target, only WinRM enabled. Output captured in-process (no console window).
- `sftp_upload`: Upload a local file to a remote host over SFTP, in-process (ssh2 â€” no scp.exe, no WSL, headless). Use to deploy scripts/configs to Linux hosts.
- `sftp_download`: Download a file from a remote host to this Windows host over SFTP, in-process (ssh2 â€” no scp.exe, no WSL, headless).
- `run_program`: Run a native executable DIRECTLY (no shell) in a hidden process and capture clean stdout/stderr + exit code. Use this for console programs like gh, git, docker, node, python, etc. -- direct execution captures their stdout/stderr without PowerShell pipeline semantics. Historical hidden-shell native stdout loss is executable/environment-specific; it is not universal. Provide the program and an args array (no shell quoting needed). For work expected to outlast the synchronous deadline, choose start_execution before launching, then poll execution_status and read_execution_output. A timeout never automatically reruns or migrates work.
- `start_remote_batch`: Opt-in process-local SSH/WinRM batch; 1–32 explicit targets, up to 8 concurrent, per-target deadline. No discovery or retry. SSH supports at most four explicit jumps. Unknown after server restart.
- `remote_batch_status`: Read ordered per-target batch records; unavailable after process restart.
- `cancel_remote_batch`: Stop dispatch of queued targets; active targets become unknown, not confirmed terminated.
- `runtime_capabilities`: Read-only runtime package, protocol, supported and available engines, transports and limits; no identity, environment or secrets.
- `start_execution`: Start a local executable directly with durable idempotency and bounded output. No shell; remote targets unsupported.
- `execution_status`: Read a local execution state. Unknown after restart means no automatic replay or verified ownership.
- `read_execution_output`: Read a bounded base64 output page, including while running.
- `cancel_execution`: Request bounded local cancellation. Windows Job Objects and Linux subreaper/pidfds confirm owned-tree termination asynchronously; failures remain unknown. Recovered runs are never signalled.
- `read_output_log`: Read a bounded raw byte page from an opt-in session log; base64 encoded. Handles are process-local and expire after one hour.
- `delete_output_log`: Delete a session log by opaque handle.

## FAQ

### Does running commands via this server interrupt my typing?

No, the server runs everything in a hidden process so it does not steal focus or spawn visible console windows.

### Can I run commands on remote Windows hosts without an SSH server?

Yes, you can use the winrm_exec tool to run commands on remote Windows hosts via PowerShell Remoting (WinRM) without needing an SSH server or agent.

### How does the server handle long-running commands?

The server enforces hard timeouts with a tree-kill mechanism to prevent runaway processes from flooding the context.
