# PowerShell MCP Server

A Model Context Protocol server for interacting with PowerShell. This server provides tools for executing PowerShell commands, retrieving system information, managing modules, and more.

## Requirements

- Node.js 18+
- PowerShell 5.1 or PowerShell Core 7+

## Installation

1. Install dependencies:
   ```bash
   npm install
   ```

2. Build the project:
   ```bash
   npm run build
   ```

## Configuration

### For Claude Desktop
Edit config: `$HOME/Library/Application\ Support/Claude/claude_desktop_config.json`

Add to mcpServers:
```json
{
  "mcpServers": {
    "mcp-powershell": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-powershell/dist/index.js"
      ]
    }
  }
}
```

### For VS Code
Edit config: `$HOME/Library/Application\ Support/Code/User/settings.json`

Add to settings:
```json
"mcp": {
  "servers": {
    "mcp-powershell": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-powershell/dist/index.js"
      ]
    }
  }
}
```

### For Cursor IDE
Edit config: `$HOME/.cursor/mcp.json`

Add to mcpServers:
```json
{
  "mcpServers": {
    "mcp-powershell": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-powershell/dist/index.js"
      ]
    }
  }
}
```

## Available Tools

This PowerShell MCP server provides the following tools:

### execute_ps
Execute a PowerShell command and get the result.

```
Parameters:
- command (string): PowerShell command to execute
```

Example usage:
```
execute_ps(command: "Get-Process | Select-Object -First 5")
```

### get_system_info
Retrieve detailed system information, including OS details, processor, memory, and PowerShell version.

```
Parameters: None
```

Example usage:
```
get_system_info()
```

### list_modules
List all installed PowerShell modules with details like name, version, and type.

```
Parameters: None
```

Example usage:
```
list_modules()
```

### get_command_help
Get detailed help for a specific PowerShell command, including syntax, parameters, and examples.

```
Parameters:
- command (string): PowerShell command to get help for
```

Example usage:
```
get_command_help(command: "Get-Process")
```

### find_commands
Search for PowerShell commands by name or pattern.

```
Parameters:
- search (string): Search term for PowerShell commands
```

Example usage:
```
find_commands(search: "Process")
```

### run_script
Run a PowerShell script file with optional parameters.

```
Parameters:
- scriptPath (string): Path to the PowerShell script file
- parameters (string, optional): Optional parameters to pass to the script
```

Example usage:
```
run_script(scriptPath: "/path/to/script.ps1", parameters: "-Name 'Test' -Value 123")
```

## Development

To run in development mode:
```bash
npm run dev
```

## Extending the Server

To add your own PowerShell tools:

1. Edit `src/index.ts`
2. Add new tools in the `registerTools()` method
3. Follow the existing pattern for consistent error handling
4. Build with `npm run build`

### Adding a Tool Example

```typescript
// In the registerTools() method:
this.server.tool(
  "my_ps_tool",
  {
    param1: z.string().describe("Description of parameter 1"),
    param2: z.number().optional().describe("Optional numeric parameter"),
  },
  async ({ param1, param2 }) => {
    try {
      // Your PowerShell command
      const command = `Your-PowerShell-Command -Param1 "${param1}" ${param2 ? `-Param2 ${param2}` : ''}`;

      const { stdout, stderr } = await execAsync(`powershell -Command "${command.replace(/"/g, '\\"')}"`);

      if (stderr) {
        return {
          isError: true,
          content: [
            {
              type: "text" as const,
              text: `Error in my_ps_tool: ${stderr}`,
            },
          ],
        };
      }

      return {
        content: [
          {
            type: "text" as const,
            text: stdout,
          },
        ],
      };
    } catch (error) {
      return {
        isError: true,
        content: [
          {
            type: "text" as const,
            text: `Error in my_ps_tool: ${(error as Error).message}`,
          },
        ],
      };
    }
  }
);
```

## Security Considerations

- This server executes PowerShell commands directly on your system
- Commands are executed with the same privileges as the process running the MCP server
- Use caution when exposing destructive operations
- Consider implementing additional validation for sensitive commands

## Troubleshooting

### Common Issues

1. **PowerShell execution policy restrictions**
   - You may need to adjust your PowerShell execution policy to allow script execution
   - Use `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` to allow local scripts

2. **Path not found errors**
   - Ensure file paths are absolute or properly relative to the working directory
   - Use appropriate path separators for your OS

3. **Command not found errors**
   - Some commands may require specific modules to be installed
   - Use `Install-Module ModuleName` to install required modules

## License

MIT