PoshMCP

# PowerShell MCP Server A Model Context Protocol (MCP) server that exposes PowerShell cmdlets as tools for AI assistants like Claude or Github Copilot. Built with security in mind through explicit whitelisting of allowed cmdlets. ## Overview This MCP server dynamically loads PowerShell cmdlets from modules and scripts, automatically generating tool schemas from cmdlet documentation. Unlike traditional PowerShell remoting, this server uses a **whitelist approach** - only explicitly configured cmdlets are exposed, making it safer for AI interactions. ### Key Features - **Declarative Configuration**: Define available tools in a simple JSON config file - **Automatic Schema Generation**: Uses PowerShell reflection to generate MCP tool schemas from cmdlet help documentation - **Security by Whitelisting**: Only explicitly listed cmdlets are exposed as tools - **Dynamic Loading**: Supports both PowerShell modules (.psm1) and script files (.ps1) - **Type Conversion**: Automatically handles parameter type conversions (DateTime, switch parameters, etc.) ## How It Works 1. **Configuration Loading**: Reads `mcp-config.json` to determine which cmdlets to expose 2. **Module/Script Import**: Loads specified PowerShell modules and dot-sources script files 3. **Schema Generation**: Uses `Get-Command` and `Get-Help` to introspect each cmdlet: - Extracts cmdlet synopsis as tool description - Maps PowerShell parameter types to JSON schema types - Identifies mandatory parameters from `[Parameter(Mandatory)]` attributes - Generates camelCase parameter names for JSON (e.g., `StartDate` → `startDate`) 4. **Tool Invocation**: When a tool is called, dynamically dispatches to the corresponding cmdlet with parameter mapping ## Installation ### From PowerShell Gallery (Recommended) ```powershell Install-Module -Name PoshMCP -Scope CurrentUser ``` ### From Source 1. Clone or download this repository to your local machine 2. Ensure PowerShell 7+ is installed (`pwsh`) ## Configuration ### MCP Server Configuration Add the following to your VS Code MCP configuration file (typically `%APPDATA%\Code\User\mcp.json` on Windows): ```json { "servers": { "posh-mcp": { "type": "stdio", "command": "pwsh", "args": [ "-NoProfile", "-NoLogo", "-Command", "Import-Module PoshMCP;", "Start-PoshMcp -ConfigPath C:\\path\\to\\your\\mcp-config.json" ] } } } ``` ### Tool Configuration Edit `mcp-config.json` to define which cmdlets to expose: ```json { "serverInfo": { "name": "posh-mcp", "version": "1.0.0" }, "modules": [ { "name": "ModuleName", "path": "./MyModule.psm1", "cmdlets": [ "Get-MyData", "Set-MyConfig" ] } ], "scripts": [ { "path": "./my-tools.ps1", "cmdlets": [ "Get-CustomInfo", "Invoke-CustomTask" ] } ] } ``` **Configuration Structure:** - **`serverInfo`**: Metadata about the MCP server - `name`: Server name displayed to MCP clients - `version`: Server version - **`modules`**: PowerShell modules to import - `name`: Module name (informational) - `path`: Relative or absolute path to the `.psm1` file - `cmdlets`: Array of cmdlet names to expose as tools - **`scripts`**: PowerShell script files to dot-source - `path`: Relative or absolute path to the `.ps1` file - `cmdlets`: Array of function names to expose as tools ## Creating Custom Tools ### Example: Creating a Custom Script Create a script file (e.g., `my-tools.ps1`): ```powershell function Get-SystemUptime { <# .SYNOPSIS Returns the system uptime information. .DESCRIPTION Gets how long the system has been running since last boot. .EXAMPLE Get-SystemUptime Returns uptime information. .OUTPUTS Hashtable with uptime details. #> [CmdletBinding()] param() $os = Get-CimInstance Win32_OperatingSystem $uptime = (Get-Date) - $os.LastBootUpTime return @{ LastBootTime = $os.LastBootUpTime.ToString("o") UptimeDays = $uptime.Days UptimeHours = $uptime.Hours UptimeMinutes = $uptime.Minutes } } ``` Add to `mcp-config.json`: ```json { "scripts": [ { "path": "./my-tools.ps1", "cmdlets": [ "Get-SystemUptime" ] } ] } ``` The tool will automatically be exposed as `getSystemUptime` (camelCase) with schema generated from the comment-based help. ### Documentation Best Practices For best results, include complete comment-based help in your cmdlets: ```powershell function Get-MyData { <# .SYNOPSIS Brief one-line description (becomes tool description) .PARAMETER Name Detailed parameter description (appears in tool schema) .PARAMETER StartDate Start date for filtering results .EXAMPLE Get-MyData -Name "Test" -StartDate "2025-01-01" #> [CmdletBinding()] param( [Parameter(Mandatory = $true)] [string]$Name, [Parameter(Mandatory = $false)] [DateTime]$StartDate = (Get-Date).AddDays(-7) ) # Your implementation } ``` ## Security Considerations ### Why This Is Safer 1. **Whitelist-Only**: Only cmdlets explicitly listed in `mcp-config.json` are accessible 2. **No Dynamic Execution**: The server doesn't execute arbitrary PowerShell commands 3. **Parameter Validation**: All parameters go through PowerShell's native validation 4. **Isolated Scope**: Each cmdlet runs in a controlled context