# 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)
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# Start the server
npm start

# Test components
npm test

# Run diagnostics
node diagnose.bat

# Start server directly  
node src/server.js
```

### Configuration Management
```bash
# 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
```bash
# 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):

```json
{
  "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
```bash
# Check Node.js version (need 18+)
node --version

# Check dependencies
npm install

# Test components
node test-server.js
```

### Claude Desktop integration issues  
```bash
# Run setup again
setup.bat

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

# Restart Claude Desktop completely
```

### PowerShell execution issues
```bash
# 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](LICENSE) file for details.

## 🔗 **Links**

- [GitHub Repository](https://github.com/gunjanjp/powershell-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/)

---

**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.