powershell-mcp

PowerShell MCP Server

A comprehensive Model Context Protocol (MCP) server that enables Claude and other LLM applications to execute PowerShell commands, scripts, and perform system operations on Windows systems.

🌟 Key Features

• 🔧 PowerShell Execution: Execute commands, run scripts, and create new PowerShell files
• 🖥️ System Monitoring: Get system info, monitor processes, check services and disk space
• 📁 File Operations: List directories, get file info, and search files with pattern matching
• ⚙️ Simple Setup: One-command installation with automatic Claude Desktop configuration
• 🛡️ Secure: Safe execution with proper error handling and session management

🛠️ Available Tools

PowerShell Tools

• execute-powershell - Execute PowerShell commands with optional working directory
• execute-powershell-script - Run PowerShell script files with parameters
• create-powershell-script - Create new PowerShell scripts

System Tools

• get-system-info - Comprehensive Windows system information
• get-process-list - Running processes with CPU/memory usage (sortable/filterable)
• get-service-status - Windows services status with filtering
• check-disk-space - Disk space usage for all or specific drives

File Tools

• list-directory - Enhanced directory listing with filtering
• get-file-info - Detailed file and directory metadata
• search-files - Recursive file search with pattern matching

📋 Prerequisites

• Windows 10/11 or Windows Server 2016+
• Node.js 18.0.0 or higher
• PowerShell 5.1+ or PowerShell Core 7+
• Claude Desktop application

🚀 Quick Setup

Option 1: Safe Automated Setup (Recommended)

# Clone and setup with configuration management
git clone https://github.com/gunjanjp/powershell-mcp.git
cd powershell-mcp
complete-setup.bat

Option 2: Configuration Recovery (If you had existing settings)

# If previous setup overwrote your existing configuration
node recovery.js status      # Check current state
node recovery.js scan        # Find backup configurations
node recovery.js restore 1   # Restore from backup
# OR
node recovery.js merge 1     # Merge backup with current config

Option 3: Manual Setup

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

# Install dependencies
npm install

# Safely add to existing configuration
node recovery.js add-powershell

# Restart Claude Desktop

📖 Usage Examples

Ask Claude:

• "Execute PowerShell: Get-Date"
• "Check my system information"
• "Show me the top 10 processes by CPU usage"
• "What's my disk space usage?"
• "List files in my Downloads folder"
• "Search for all .txt files in C:\Users"
• "Create a PowerShell script to backup my Documents folder"

🔧 Commands

Server Commands

# Start the server
npm start

# Test components
npm test

# Run diagnostics
node diagnose.bat

# Start server directly  
node src/server.js

Configuration Management

# Check configuration status
node recovery.js status

# Find backup configurations
node recovery.js scan

# Safely add PowerShell server
node recovery.js add-powershell

# Restore from backup
node recovery.js restore <number>

# Merge configurations
node recovery.js merge <number>

# Show backup contents
node recovery.js show <number>

Quick Setup Commands

# Complete setup with safety checks
complete-setup.bat

# Test server only
run-test.bat

📁 Project Structure

powershell-mcp/
├── src/
│   ├── server.js           # Main MCP server (with stderr logging fix)
│   ├── tools/              # Tool implementations
│   │   ├── powershell-tools.js
│   │   ├── system-tools.js
│   │   └── file-tools.js
│   └── utils/              # Utility modules
│       └── system-utils.js
├── examples/               # Example PowerShell scripts
├── scripts/               # Setup utilities
├── test/                  # Test files
├── claude_desktop_config.json  # Claude Desktop configuration
├── setup.bat             # Automated setup script
├── diagnose.bat          # Diagnostic tool
├── test-server.js        # Component testing
└── README.md

⚙️ Claude Desktop Configuration

The server uses this configuration (automatically applied by setup):

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["D:/claude/claude-powershell-mcp/src/server.js"],
      "env": {}
    }
  }
}

Config location: %APPDATA%\Claude\claude_desktop_config.json

🛡️ Security Features

• Safe Execution: Uses -ExecutionPolicy Bypass and -NoProfile for security
• Input Validation: All inputs validated with Zod schemas
• Session Management: PowerShell sessions properly disposed after use
• Error Handling: Comprehensive error handling prevents system issues
• Logging: All operations logged to stderr (not interfering with JSON-RPC)

🐛 Troubleshooting

Server won't start

# Check Node.js version (need 18+)
node --version

# Check dependencies
npm install

# Test components
node test-server.js

Claude Desktop integration issues

# Run setup again
setup.bat

# Check configuration
type "%APPDATA%\Claude\claude_desktop_config.json"

# Restart Claude Desktop completely

PowerShell execution issues

# Test PowerShell
powershell -Command "Get-Date"

# Check execution policy
Get-ExecutionPolicy

# Run diagnostics
node diagnose.bat

🔄 Recent Updates (v1.1.2)

Configuration Management Improvements

• ✅ Safe Configuration Management - No more overwriting existing configs
• ✅ Automatic Backups - Creates backups before any configuration changes
• ✅ Configuration Recovery - Tools to find and restore previous configurations
• ✅ Merge Capability - Intelligent merging of multiple MCP server configs
• ✅ Interactive Recovery - Step-by-step configuration recovery process

Previous Fixes (v1.1.1)

• ✅ Fixed Claude Desktop JSON parsing error - Changed console.log to console.error (stderr)
• ✅ Cleaned up project structure - Removed redundant server files
• ✅ Simplified setup - One script setup process
• ✅ Proper error handling - Enhanced logging and error management

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Make changes and test: npm test
4. Commit: git commit -am 'Add feature'
5. Push: git push origin feature-name
6. Submit pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Model Context Protocol
• Claude Desktop

---

Made with ❤️ for the Claude and PowerShell communities

⚠️ Important: This tool provides direct access to PowerShell commands. Use responsibly and be aware of security implications.