MCP PowerShell Server. README>

An MCP (Model Context Protocol) server for executing PowerShell scripts, supporting both HTTP and STDIO modes of operation.

In This Article

Description

The MCP PowerShell Server allows AI assistants to execute PowerShell commands and scripts via the standardized MCP protocol. The server supports two modes of operation:

STDIO mode: For integration with gemini-cli and other local MCP clients.
HTTP mode: For web applications and network integration via a REST API.

Which mode to choose: HTTP or STDIO?

The choice between mcp-powershell-http.ps1 and mcp-powershell-stdio.ps1 depends on how and from where the client application will interact with the server.

mcp-powershell-http.ps1 (HTTP mode) works like a waiter in a restaurant. It takes orders (HTTP requests) from any client on the network, passes them to the “kitchen” (PowerShell), and returns the finished result (HTTP response).
mcp-powershell-stdio.ps1 (STDIO mode) works like a personal assistant in the kitchen. It receives tasks directly (via standard input stdin) from a managing process (e.g., gemini-cli) that launched it, and immediately returns the result (via standard output stdout).

When to use HTTP mode

You should choose HTTP if network communication is required.

Remote management: The client application is on a different computer.
Web integration: You need to call PowerShell scripts from a web application, admin panel, or via AJAX requests.
Microservice architecture: Other services on your network need to interact with PowerShell.
Simple testing: You want to use tools like curl, Postman, or Invoke-RestMethod to send commands.

In simple terms: choose HTTP if there is a network between the client and the server.

When to use STDIO mode

This mode is ideal for local and secure integration.

Primary scenario — Gemini CLI: The gemini-cli tool launches mcp-powershell-stdio.ps1 as a child process and communicates with it directly through standard input/output streams.
Integration with other local applications: Your program in Python, Node.js, or another language can start and manage the server without opening network ports.
Enhanced security: Since no network ports are opened, this method is more secure by default.

In simple terms: choose STDIO if the client and server are on the same machine, and the client launches the server itself.

Comparison Table

Characteristic	HTTP mode (`mcp-powershell-http.ps1`)	STDIO mode (`mcp-powershell-stdio.ps1`)
Primary Scenario	Network communication, web API	Local integration with CLI tools
Communication Type	Client-server over the network (TCP/IP)	Inter-process communication (IPC)
Location	Client and server can be on different machines	Client and server must be on the same machine
Security	Requires attention (port access, firewall)	More secure by default (no open ports)
Typical Clients	`curl`, Postman, web applications, remote scripts	`gemini-cli`, local wrapper applications

Features

✅ Support for MCP protocol version 2024-11-05
✅ Two modes of operation: STDIO and HTTP
✅ Isolation of script execution in separate PowerShell processes
✅ Configurable execution timeouts
✅ Detailed logging of all operations
✅ Handling of PowerShell errors and warnings
✅ Support for script parameters
✅ Configurable working directory
✅ Automatic launchers for easy startup

System Requirements

PowerShell 7.0 or newer
Windows 10/11 or Windows Server 2019+
.NET 6.0 or newer

Project Structure

mcp-powershell-server/
├── src/
│   ├── clients/           # Client applications
│   │   ├── node/         # Node.js client
│   │   ├── powershell/   # PowerShell client
│   │   └── python/       # Python client
│   └── servers/          # Server components
│       ├── mcp-powershell-stdio.ps1   # STDIO version of the server
│       ├── mcp-powershell-http.ps1    # HTTP version of the server
│       ├── test-mcp.ps1               # Test server
│       └── config.json                # Configuration file
├── docs/                 # Documentation
├── README.md            # This file
└── how-to-use.md        # Detailed user guide

Quick Start

STDIO mode (for gemini-cli)

Start the server:
powershell .\src\servers\mcp-powershell-stdio.ps1
Test:
powershell .\src\servers\test-mcp.ps1

HTTP mode

Basic start:
powershell .\src\servers\mcp-powershell-http.ps1
With custom parameters:
powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
With a configuration file:
powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Available MCP Tools

`run-script`

Executes a PowerShell script with specified parameters.

Parameters:

script (required) – PowerShell code to execute
parameters (optional) – Hashtable of parameters
workingDirectory (optional) – The working directory
timeoutSeconds (optional) – Execution timeout (1-3600 sec)

Example usage via MCP:

{
  "name": "run-script",
  "arguments": {
    "script": "Get-Process | Select-Object -First 5 | Format-Table",
    "workingDirectory": "C:\\",
    "timeoutSeconds": 30
  }
}

Configuration

The server supports configuration via the config.json file:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Tools\\"
  ],
  "Security": {
    "EnableScriptValidation": true,
    "BlockDangerousCommands": true,
    "RestrictedCommands": [
      "Remove-Item",
      "Format-Volume",
      "Stop-Computer",
      "Restart-Computer"
    ]
  }
}

Security

Script execution occurs in isolated PowerShell processes
Support for a list of forbidden commands
Execution time limit
Logging of all executed commands
Ability to restrict accessible paths

Logging

STDIO mode: Logs are written to %TEMP%\mcp-powershell-server.log
HTTP mode: Logs are output to the console with color highlighting

Log levels: DEBUG, INFO, WARNING, ERROR

Integration with AI Assistants

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Show the first 5 processes in the system"

Other MCP Clients

The server is compatible with all clients that support the MCP protocol 2024-11-05.

Troubleshooting

Common Problems

Port is busy: Change the port in the configuration or stop the process using the port.
Access rights: Running on privileged ports (<1024) requires administrator rights.
Encoding: Ensure that PowerShell is configured for UTF-8.
PowerShell version: Requires PowerShell 7+.

Diagnostics

Check the server logs to diagnose problems:

Get-Content "$env:TEMP\mcp-powershell-server.log" -Tail 20

Development and Extension

The server can be easily extended with new MCP tools. See how-to-use.md for detailed development instructions.

License

This project is distributed under the MIT License. See the LICENSE file for details.

Support

Create an Issue in the GitHub repository
Check the documentation in how-to-use.md
Review the usage examples

Versions

1.0.0 – Initial version with support for STDIO and HTTP modes