powershell-mcp

A powerful MCP (Model Context Protocol) server that enables Claude to execute PowerShell commands on Windows systems. Supports both PowerShell 7+ (pwsh.exe) and Windows PowerShell 5.1 (powershell.exe).

⚠️ Security Warning: This server executes arbitrary PowerShell commands. Use with caution and only in trusted environments.

Features

• Dual PowerShell Support: Use modern PowerShell 7+ or legacy Windows PowerShell 5.1
• Smart Defaults: Automatically detects and uses PowerShell 7 by default
• Background Processes: Run and manage long-running PowerShell scripts
• Output Management: Automatic truncation and file saving for large outputs
• Script Execution: Run .ps1 script files with arguments
• Version Detection: Check which PowerShell versions are available
• Configurable: Environment variables for customization

Installation

Option 1: Local Development (Current)

cd C:\Users\shaun\repos\mcp-powershell
npm install

Option 2: NPM Global (Future)

npm install -g powershell-mcp

Quick Start

For Claude Desktop (Local Development)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["C:\\Users\\shaun\\repos\\mcp-powershell\\index.js"]
    }
  }
}

For Claude Desktop (NPM Package - Future)

{
  "mcpServers": {
    "powershell": {
      "command": "npx",
      "args": ["powershell-mcp"]
    }
  }
}

Configuration Options

You can customize behavior using environment variables:

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["C:\\Users\\shaun\\repos\\mcp-powershell\\index.js"],
      "env": {
        "POWERSHELL_MCP_DEFAULT_SHELL": "pwsh",
        "POWERSHELL_MCP_MAX_OUTPUT_SIZE": "102400",
        "POWERSHELL_MCP_TEMP_DIR": "C:\\temp\\powershell-mcp",
        "POWERSHELL_MCP_PWSH_PATH": "pwsh.exe",
        "POWERSHELL_MCP_POWERSHELL_PATH": "powershell.exe"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
POWERSHELL_MCP_DEFAULT_SHELL	pwsh	Default shell to use: pwsh or powershell
POWERSHELL_MCP_MAX_OUTPUT_SIZE	51200 (50KB)	Max output size before truncation
POWERSHELL_MCP_TEMP_DIR	System temp	Directory for storing full outputs
POWERSHELL_MCP_PWSH_PATH	pwsh.exe	Path to PowerShell 7 executable
POWERSHELL_MCP_POWERSHELL_PATH	powershell.exe	Path to Windows PowerShell 5.1 executable

Available Tools

run - Execute PowerShell Command

Execute any PowerShell command with full control over which version to use.

Parameters:

• command (string, required): PowerShell command to execute
• cwd (string, optional): Working directory
• timeout (number, optional): Timeout in milliseconds (default: 30000)
• useLegacy (boolean, optional): Use PowerShell 5.1 instead of 7 (default: false)
• asJson (boolean, optional): Parse output as JSON if possible (default: false)

Examples:

// Simple command (uses PowerShell 7)
run("Get-Process | Select-Object -First 5")

// With working directory
run("Get-ChildItem", { cwd: "C:\\Projects" })

// Use legacy PowerShell 5.1 for compatibility
run("Get-WindowsFeature", { useLegacy: true })

// Parse JSON output
run("Get-Process | Select-Object Name, Id | ConvertTo-Json", { asJson: true })

run_script - Execute PowerShell Script File

Run a .ps1 script file with arguments.

Parameters:

• scriptPath (string, required): Path to .ps1 file
• args (array, optional): Arguments to pass to script
• cwd (string, optional): Working directory
• timeout (number, optional): Timeout in milliseconds (default: 30000)
• useLegacy (boolean, optional): Use PowerShell 5.1 (default: false)

Example:

run_script("C:\\Scripts\\Deploy.ps1", {
  args: ["Production", "v1.2.3"],
  cwd: "C:\\Projects\\MyApp"
})

get_version - Check PowerShell Versions

Get detailed version information for both PowerShell installations.

Example:

get_version()

Returns:

{
  "success": true,
  "available": {
    "pwsh": true,
    "powershell": true
  },
  "defaultShell": "pwsh",
  "versions": {
    "PowerShell 7": {
      "PSVersion": "7.5.4",
      "PSEdition": "Core"
    },
    "PowerShell 5.1": {
      "PSVersion": "5.1.26100.6899",
      "PSEdition": "Desktop"
    }
  }
}

run_background - Start Background Process

Run a long-running PowerShell command in the background.

Parameters:

• command (string, required): PowerShell command
• name (string, required): Unique name for the process
• cwd (string, optional): Working directory
• useLegacy (boolean, optional): Use PowerShell 5.1 (default: false)

Example:

run_background("npm run dev", "frontend-server")

kill_background - Stop Background Process

Kill a background process by name.

Parameters:

• name (string, required): Name of the process to kill

Example:

kill_background("frontend-server")

list_background - List Background Processes

List all running background processes with their status.

Example:

list_background()

PowerShell 7 vs Windows PowerShell 5.1

PowerShell 7 (pwsh.exe) - Default

Advantages:

• Modern features and better performance
• Cross-platform cmdlets
• Regular updates
• Better JSON handling
• Improved error messages

Use when:

• Doing general scripting tasks
• Working with modern APIs
• Need latest PowerShell features

Windows PowerShell 5.1 (powershell.exe)

Advantages:

• Comes with Windows
• Some legacy modules only work here
• Certain Windows management tools

Use when:

• Need specific Windows-only modules
• Working with legacy scripts
• Compatibility requirements

Example - Using Legacy Mode:

// Some Windows features require PowerShell 5.1
run("Get-WindowsFeature", { useLegacy: true })

Output Handling

When command output exceeds POWERSHELL_MCP_MAX_OUTPUT_SIZE:

1. Output is truncated to the specified limit
2. Full output is saved to a temporary file
3. Response includes the file path for accessing complete output
4. Falls back to system temp directory if custom temp dir fails

Example Response with Overflow:

{
  "success": true,
  "stdout": "...[truncated]...\n\n[Output truncated - exceeded 51200 bytes]\n[Full output saved to: C:\\temp\\powershell-mcp-stdout-2025-10-26.txt]",
  "overflow": true,
  "details": {
    "stdout": {
      "originalSize": 150000,
      "truncatedSize": 51200,
      "filePath": "C:\\temp\\powershell-mcp-stdout-2025-10-26.txt"
    }
  }
}

Response Format

All tools return JSON responses:

{
  "success": true,
  "stdout": "command output",
  "stderr": "error output if any",
  "command": "executed command",
  "shell": "PowerShell 7"
}

Usage Examples

Check System Processes

Get-Process | Sort-Object CPU -Descending | Select-Object -First 10

Manage Services

# List all services
Get-Service

# Start a service (requires admin)
Start-Service -Name "wuauserv"

Work with Files

# Get files modified in last 24 hours
Get-ChildItem -Recurse | Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-1) }

Network Information

# Get network adapters
Get-NetAdapter | Select-Object Name, Status, LinkSpeed

# Test connectivity
Test-NetConnection -ComputerName google.com -Port 443

Security Considerations

This MCP server executes arbitrary PowerShell commands with the same privileges as the Node.js process.

Best Practices:

• Only use in development environments or trusted contexts
• Run with least privilege necessary
• Review commands before execution when possible
• Use appropriate execution policies
• Monitor background processes

Requirements

• Node.js >= 16.0.0
• Windows 10/11 or Windows Server
• PowerShell 7+ (recommended) or Windows PowerShell 5.1

Troubleshooting

PowerShell 7 Not Found

If you get errors about pwsh.exe not being found:

1. Install PowerShell 7 from Microsoft Store or https://github.com/PowerShell/PowerShell
2. Or configure to use Windows PowerShell 5.1 by default:

{
  "env": {
    "POWERSHELL_MCP_DEFAULT_SHELL": "powershell"
  }
}

Execution Policy Errors

If you see execution policy errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Permission Errors

Some commands require administrator privileges. Run Claude Desktop as administrator if needed.

Development

# Clone repository
git clone https://github.com/YourUsername/mcp-powershell.git
cd mcp-powershell

# Install dependencies
npm install

# Run locally
node index.js

License

MIT

Author

Shaun Prince

Contributing

Issues and pull requests are welcome at GitHub.

Acknowledgments

Inspired by bash-mcp by tinywind.