mcp-powershell

This MCP server provides a hardware-efficient way to execute PowerShell commands from MCP clients. It runs a Node.js-based PowerShell shell server (mcp-shell-server.mjs) and exposes a dedicated run_shell_command tool that executes PowerShell scripts or commands with memory and timeout protections. By default, it uses pwsh.exe as the PowerShell executable, with safe defaults for output buffering and timeout limits. Clients can configure their MCP settings to point at this server and, optionally, override the shell executable via MCP_SHELL_EXE. When using the tool, you supply a PowerShell command or script and receive structured output including stdout, stderr, exit code, and status flags. This is particularly useful for AI assistants that need direct PowerShell access on Windows without Bash translation layers.

Prerequisites:

• Node.js 18+ installed on Windows (per Windows OS requirement)
• npm (comes with Node.js)

Step-by-step installation:

1. Clone or download the MCP PowerShell server repository.
2. In the project root, install dependencies: npm install
3. Start the server locally to verify: node mcp-shell-server.mjs
4. (Optional) Configure the MCP client to use the server by adding an entry for mcp-powershell-server in your MCP client config, pointing to the server script and, if needed, overriding the PowerShell executable via MCP_SHELL_EXE.

Notes:

• Ensure PowerShell (pwsh.exe) is installed on the host and accessible in PATH, or override via MCP_SHELL_EXE.
• The default environment is designed for Windows, with cross-platform MCP client compatibility.

Tips and considerations:

• The server uses memory-optimized output buffering with a default 64KB per stream and a maximum of 2MB per stream. If you anticipate large outputs, adjust maxOutputBytes in the client request.
• Commands run with user permissions; consider applying your own whitelisting or sandboxing for production deployments.
• The MCP shell can be overridden via the MCP_SHELL_EXE environment variable to point to pwsh.exe or powershell.exe depending on your environment.
• Timeout protection is enforced with a default of 60 seconds and a maximum of 10 minutes; customize timeoutMs per request as needed.
• If you need to terminate long-running processes, the server supports process-tree termination via taskkill on Windows.
• Ensure network and security policies allow Node.js-based MCP servers to communicate with MCP clients in your environment.