PowerShell Exec MCP Server
A secure Model Context Protocol (MCP) server that provides controlled PowerShell command execution capabilities through MCP tools. This server includes security features to prevent dangerous commands, provides timeouts for command execution, and specializes in enterprise script generation for Microsoft Intune and IBM BigFix management platforms.
Features
- Secure PowerShell command execution
- JSON-formatted output for structured data
- System information retrieval
- Service management and monitoring
- Process monitoring and analysis
- Event log access
- PowerShell script generation
- Template-based script generation
- Dynamic script generation
- Microsoft Intune detection and remediation script generation
- IBM BigFix relevance and action script generation
- Command timeout support
- Blocking of dangerous commands
- Non-interactive and profile-less execution
- Async support
- Type hints and input validation
Project Structure
mcp-powershell-exec/
├── mcp_powershell_exec/ # Main package directory
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Entry point
│ ├── server.py # Server implementation
│ ├── templates/ # PowerShell script templates
│ │ ├── basic_script.ps1 # Basic script template
│ │ ├── system_inventory.ps1 # System inventory template
│ │ ├── intune_detection.ps1 # Intune detection script template
│ │ ├── intune_remediation.ps1 # Intune remediation script template
│ │ ├── bigfix_relevance.ps1 # BigFix relevance script template
│ │ └── bigfix_action.ps1 # BigFix action script template
│ └── py.typed # Type hints marker
├── pyproject.toml # Project metadata and dependencies
├── setup.py # Package installation
└── README.md # Documentation
Installation
Installing via Smithery
To install PowerShell Exec Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @DynamicEndpoints/powershell-exec-mcp-server --client claude
Manual Installation
- Ensure you have Python 3.7+ installed
- Install the package:
pip install .
Or install in development mode:
pip install -e .
Usage
Running the Server
You can run the server in several ways:
- Using the MCP CLI:
mcp run mcp_powershell_exec
- Using Python module:
python -m mcp_powershell_exec
- Using the console script:
mcp-powershell-exec
For development and testing:
mcp dev mcp_powershell_exec
Installing in Claude Desktop
To install the server in Claude Desktop:
mcp install mcp_powershell_exec
Available Tools
run_powershell
The base tool for executing PowerShell commands securely with timeout support.
Parameters:
code(required): PowerShell code to executetimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await run_powershell(
code="Get-Process | Select-Object Name, Id, CPU",
timeout=30
)
get_system_info
Retrieve system information using Get-ComputerInfo cmdlet.
Parameters:
properties(optional): List of ComputerInfo properties to retrievetimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await get_system_info(
properties=["OsName", "OsVersion", "OsArchitecture"]
)
get_running_services
Get information about Windows services.
Parameters:
name(optional): Filter services by name (supports wildcards)status(optional): Filter by status (Running, Stopped, etc.)timeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await get_running_services(
name="*sql*",
status="Running"
)
get_processes
Monitor running processes with filtering and sorting capabilities.
Parameters:
name(optional): Filter processes by name (supports wildcards)top(optional): Limit to top N processessort_by(optional): Property to sort by (e.g., CPU, WorkingSet)timeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await get_processes(
top=5,
sort_by="CPU"
)
get_event_logs
Access Windows event logs with filtering capabilities.
Parameters:
logname(required): Name of the event log (System, Application, Security, etc.)newest(optional): Number of most recent events to retrieve (default 10)level(optional): Filter by event level (1: Critical, 2: Error, 3: Warning, 4: Information)timeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await get_event_logs(
logname="System",
newest=5,
level=2 # Error events only
)
generate_script_from_template
Generate PowerShell scripts using predefined templates.
Parameters:
template_name(required): Name of the template to use (without .ps1 extension)parameters(required): Dictionary of parameters to replace in the templateoutput_path(optional): Where to save the generated scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_script_from_template(
template_name="basic_script",
parameters={
"SYNOPSIS": "My Test Script",
"DESCRIPTION": "A test script generated from template",
"PARAM1_DESCRIPTION": "First parameter",
"PARAM2_DESCRIPTION": "Second parameter",
"PARAM1_MANDATORY": "true",
"PARAM2_MANDATORY": "false",
"PARAM1_DEFAULT": "",
"PARAM2_DEFAULT": "default_value",
"MAIN_CODE": "Write-Host 'Hello World!'"
},
output_path="test_script.ps1"
)
generate_custom_script
Generate custom PowerShell scripts based on description.
Parameters:
description(required): Natural language description of what the script should doscript_type(required): Type of script to generate (file_ops, service_mgmt, etc.)parameters(optional): List of parameters the script should acceptinclude_logging(optional): Whether to include logging functions (default: true)include_error_handling(optional): Whether to include error handling (default: true)output_path(optional): Where to save the generated scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_custom_script(
description="Script to monitor CPU usage and log high utilization",
script_type="monitoring",
parameters=[
{
"name": "ThresholdPercent",
"type": "int",
"mandatory": "true",
"default": "90"
},
{
"name": "LogPath",
"type": "string",
"mandatory": "false",
"default": "cpu_usage.log"
}
],
output_path="monitor_cpu.ps1"
)
generate_intune_detection_script
Generate Intune detection scripts with proper exit codes and logging.
Parameters:
description(required): What the script should detectdetection_logic(required): PowerShell code that performs the detectionoutput_path(optional): Where to save the scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_intune_detection_script(
description="Check if Chrome is installed with correct version",
detection_logic="""
$app = Get-ItemProperty HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe
$version = (Get-Item $app.Path).VersionInfo.FileVersion
$compliant = [version]$version -ge [version]"100.0.0.0"
Complete-Detection -Compliant $compliant -Message "Chrome version: $version"
""",
output_path="detect_chrome.ps1"
)
generate_intune_remediation_script
Generate Intune remediation scripts with system restore points and error handling.
Parameters:
description(required): What the script should remediateremediation_logic(required): PowerShell code that performs the remediationoutput_path(optional): Where to save the scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_intune_remediation_script(
description="Install or update Chrome browser",
remediation_logic="""
$installer = "C:\\Windows\\Temp\\ChromeSetup.exe"
Invoke-WebRequest -Uri "https://dl.google.com/chrome/install/latest/chrome_installer.exe" -OutFile $installer
Start-Process -FilePath $installer -Args "/silent /install" -Wait
Remove-Item $installer
Complete-Remediation -Success $true -Message "Chrome installation completed"
""",
output_path="remedy_chrome.ps1"
)
generate_intune_script_pair
Generate both detection and remediation scripts as a matched pair.
Parameters:
description(required): What the scripts should detect and remediatedetection_logic(required): PowerShell code that performs the detectionremediation_logic(required): PowerShell code that performs the remediationoutput_dir(optional): Directory to save the scriptstimeout(optional): Command timeout in seconds (1-300, default 60)
Example Usage:
- Software Installation Check:
result = await generate_intune_script_pair(
description="Manage Chrome browser installation and version",
detection_logic="""
$app = Get-ItemProperty HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe
$version = (Get-Item $app.Path).VersionInfo.FileVersion
$compliant = [version]$version -ge [version]"100.0.0.0"
Complete-Detection -Compliant $compliant -Message "Chrome version: $version"
""",
remediation_logic="""
$installer = "C:\\Windows\\Temp\\ChromeSetup.exe"
Invoke-WebRequest -Uri "https://dl.google.com/chrome/install/latest/chrome_installer.exe" -OutFile $installer
Start-Process -FilePath $installer -Args "/silent /install" -Wait
Remove-Item $installer
Complete-Remediation -Success $true -Message "Chrome installation completed"
""",
output_dir="chrome_scripts"
)
- BitLocker Encryption:
result = await generate_intune_script_pair(
description="Check and enable BitLocker encryption on system drive",
detection_logic="""
$systemDrive = $env:SystemDrive
$bitlockerVolume = Get-BitLockerVolume -MountPoint $systemDrive
$compliant = $bitlockerVolume.ProtectionStatus -eq 'On'
Complete-Detection -Compliant $compliant -Message "BitLocker status: $($bitlockerVolume.ProtectionStatus)"
""",
remediation_logic="""
$systemDrive = $env:SystemDrive
Enable-BitLocker -MountPoint $systemDrive -TpmProtector -UsedSpaceOnly
Backup-BitLockerKeyProtector -MountPoint $systemDrive -KeyProtectorId $bitlockerVolume.KeyProtector[0].KeyProtectorId
Complete-Remediation -Success $true -Message "BitLocker enabled with TPM protection"
""",
output_dir="bitlocker_scripts"
)
- Windows Update Configuration:
result = await generate_intune_script_pair(
description="Check and configure Windows Update settings",
detection_logic="""
$wu = New-Object -ComObject Microsoft.Update.AutoUpdate
$settings = $wu.Settings
$compliant = ($settings.NotificationLevel -eq 4) -and ($settings.NoAutoRebootWithLoggedOnUsers -eq $true)
Complete-Detection -Compliant $compliant -Message "Windows Update settings status"
""",
remediation_logic="""
$wu = New-Object -ComObject Microsoft.Update.AutoUpdate
$settings = $wu.Settings
$settings.NotificationLevel = 4
$settings.NoAutoRebootWithLoggedOnUsers = $true
$settings.Save()
Complete-Remediation -Success $true -Message "Windows Update settings configured"
""",
output_dir="windows_update_scripts"
)
- Security Settings:
result = await generate_intune_script_pair(
description="Check and configure basic Windows security settings",
detection_logic="""
$firewall = Get-NetFirewallProfile
$uac = (Get-ItemProperty HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System).EnableLUA
$screenSaver = (Get-ItemProperty 'HKCU:\\Control Panel\\Desktop').ScreenSaveActive
$compliant = ($firewall.Enabled -contains $true) -and ($uac -eq 1) -and ($screenSaver -eq 1)
Complete-Detection -Compliant $compliant -Message "Security settings status"
""",
remediation_logic="""
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True
Set-ItemProperty -Path HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -Name EnableLUA -Value 1
Set-ItemProperty -Path 'HKCU:\\Control Panel\\Desktop' -Name ScreenSaveActive -Value 1
Complete-Remediation -Success $true -Message "Security settings configured"
""",
output_dir="security_scripts"
)
BigFix Script Generation Tools
generate_bigfix_relevance_script
Generate BigFix relevance scripts to determine if computers need action.
Parameters:
description(required): What the script should checkrelevance_logic(required): PowerShell code that determines relevanceoutput_path(optional): Where to save the scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_bigfix_relevance_script(
description="Check if Chrome needs updating to version 100.0.0.0",
relevance_logic="""
try {
$app = Get-ItemProperty "HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe" -ErrorAction Stop
$version = (Get-Item $app.'(Default)').VersionInfo.FileVersion
$needsUpdate = [version]$version -lt [version]"100.0.0.0"
Complete-Relevance -Relevant $needsUpdate -Message "Chrome version: $version (Target: 100.0.0.0+)"
} catch {
Complete-Relevance -Relevant $true -Message "Chrome not found - installation needed"
}
""",
output_path="chrome_relevance.ps1"
)
generate_bigfix_action_script
Generate BigFix action scripts to perform remediation or configuration changes.
Parameters:
description(required): What the script should accomplishaction_logic(required): PowerShell code that performs the actionoutput_path(optional): Where to save the scripttimeout(optional): Command timeout in seconds (1-300, default 60)
Example:
result = await generate_bigfix_action_script(
description="Install Chrome browser to latest version",
action_logic="""
try {
$installer = "$env:TEMP\\ChromeSetup.exe"
Write-BigFixLog "Downloading Chrome installer..."
Invoke-WebRequest -Uri "https://dl.google.com/chrome/install/latest/chrome_installer.exe" -OutFile $installer -UseBasicParsing
Write-BigFixLog "Installing Chrome silently..."
Start-Process -FilePath $installer -Args "/silent /install" -Wait
Remove-Item $installer -Force
Complete-Action -Result "Success" -Message "Chrome installation completed successfully"
} catch {
Complete-Action -Result "RetryableFailure" -Message "Chrome installation failed: $($_.Exception.Message)"
}
""",
output_path="chrome_action.ps1"
)
generate_bigfix_script_pair
Generate both relevance and action scripts as a matched pair for BigFix fixlet deployment.
Parameters:
description(required): What the scripts should accomplishrelevance_logic(required): PowerShell code that determines relevanceaction_logic(required): PowerShell code that performs the actionoutput_dir(optional): Directory to save the scriptstimeout(optional): Command timeout in seconds (1-300, default 60)
Example Usage:
- Chrome Browser Management:
result = await generate_bigfix_script_pair(
description="Manage Chrome browser installation with version 100.0.0.0 or higher",
relevance_logic="""
try {
$app = Get-ItemProperty "HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe" -ErrorAction Stop
$version = (Get-Item $app.'(Default)').VersionInfo.FileVersion
$needsAction = [version]$version -lt [version]"100.0.0.0"
Complete-Relevance -Relevant $needsAction -Message "Chrome version: $version (Target: 100.0.0.0+)"
} catch {
Complete-Relevance -Relevant $true -Message "Chrome not found - installation needed"
}
""",
action_logic="""
try {
$installer = "$env:TEMP\\ChromeSetup.exe"
Write-BigFixLog "Downloading Chrome installer..."
Invoke-WebRequest -Uri "https://dl.google.com/chrome/install/latest/chrome_installer.exe" -OutFile $installer -UseBasicParsing
Write-BigFixLog "Installing Chrome silently..."
Start-Process -FilePath $installer -Args "/silent /install" -Wait
Remove-Item $installer -Force
Complete-Action -Result "Success" -Message "Chrome installation completed successfully"
} catch {
Complete-Action -Result "RetryableFailure" -Message "Chrome installation failed: $($_.Exception.Message)"
}
""",
output_dir="chrome_bigfix_scripts"
)
- Windows Update Configuration:
result = await generate_bigfix_script_pair(
description="Ensure Windows Update service is running and configured properly",
relevance_logic="""
$service = Get-Service -Name "wuauserv" -ErrorAction SilentlyContinue
$needsAction = ($service.Status -ne "Running") -or ($service.StartType -ne "Automatic")
Complete-Relevance -Relevant $needsAction -Message "Windows Update service status: $($service.Status), StartType: $($service.StartType)"
""",
action_logic="""
try {
Set-Service -Name "wuauserv" -StartupType Automatic
Start-Service -Name "wuauserv"
Complete-Action -Result "Success" -Message "Windows Update service configured and started"
} catch {
Complete-Action -Result "RetryableFailure" -Message "Failed to configure Windows Update service: $($_.Exception.Message)"
}
""",
output_dir="windows_update_bigfix_scripts"
)
- Security Settings Configuration:
result = await generate_bigfix_script_pair(
description="Ensure basic Windows security settings are properly configured",
relevance_logic="""
$firewall = Get-NetFirewallProfile
$uac = (Get-ItemProperty HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System).EnableLUA
$firewallOk = ($firewall | Where-Object { $_.Enabled -eq $false }).Count -eq 0
$needsAction = (-not $firewallOk) -or ($uac -ne 1)
Complete-Relevance -Relevant $needsAction -Message "Security settings check - Firewall OK: $firewallOk, UAC Enabled: $($uac -eq 1)"
""",
action_logic="""
try {
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True
Set-ItemProperty -Path HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -Name EnableLUA -Value 1
Complete-Action -Result "Success" -Message "Security settings configured successfully"
} catch {
Complete-Action -Result "RetryableFailure" -Message "Failed to configure security settings: $($_.Exception.Message)"
}
""",
output_dir="security_bigfix_scripts"
)
Security Features
The server implements several security measures:
-
Blocks dangerous commands like:
- Recursive deletions
- Drive formatting
- System shutdown/restart
- Service manipulation
- User account manipulation
- Dynamic code execution
-
Command timeout enforcement
-
Non-interactive mode to prevent hangs
-
No profile loading to ensure clean execution environment
-
JSON output formatting for consistent data structures
-
Input validation for all tool parameters
Development
The project uses modern Python packaging tools and includes full type hints support. To set up a development environment:
- Clone the repository
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install development dependencies:
pip install -e .
Contributing
Contributions are welcome! Please ensure any changes maintain the security standards of the server.
License
MIT License