run_powershell
Execute PowerShell commands securely with configurable timeouts for system management, automation tasks, and enterprise script execution.
Instructions
Execute PowerShell commands securely.
Args:
code: PowerShell code to execute
timeout: Command timeout in seconds (1-300, default 60)
ctx: MCP context for logging and progress reporting
Returns:
Command output as string
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| timeout | No | ||
| ctx | No |
Input Schema (JSON Schema)
{
"properties": {
"code": {
"title": "Code",
"type": "string"
},
"ctx": {
"anyOf": [
{
"$ref": "#/$defs/Context"
},
{
"type": "null"
}
],
"default": null
},
"timeout": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": 60,
"title": "Timeout"
}
},
"required": [
"code"
],
"type": "object"
}
Implementation Reference
- run.py:75-139 (handler)The tool call handler that specifically handles 'run_powershell' by validating inputs and executing PowerShell code via asyncio subprocess with timeout and error handling.async def handle_tool_call(request): if request.params.name != "run_powershell": raise McpError( ErrorCode.MethodNotFound, f"Unknown tool: {request.params.name}" ) code = request.params.arguments.get("code") if not isinstance(code, str): raise McpError( ErrorCode.InvalidParams, "code parameter must be a string" ) timeout = request.params.arguments.get("timeout", 60) if not isinstance(timeout, int) or timeout < 1 or timeout > 300: raise McpError( ErrorCode.InvalidParams, "timeout must be between 1 and 300 seconds" ) try: process = await asyncio.create_subprocess_exec( "powershell", "-NoProfile", "-NonInteractive", "-Command", code, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True ) stdout, stderr = await asyncio.wait_for( process.communicate(), timeout=timeout ) if process.returncode != 0: raise McpError( ErrorCode.InternalError, stderr or "Command failed with no error output" ) return { "content": [ { "type": "text", "text": stdout } ] } except asyncio.TimeoutError: process.kill() raise McpError( ErrorCode.Timeout, f"Command timed out after {timeout} seconds" ) except Exception as e: raise McpError( ErrorCode.InternalError, str(e) )
- run.py:45-72 (registration)Registers the 'run_powershell' tool by listing it in the ListTools response, including name, description, and schema.@server.setRequestHandler(ListToolsRequestSchema) async def handle_list_tools(): return { "tools": [ { "name": "run_powershell", "description": "Execute PowerShell commands securely", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "PowerShell code to execute" }, "timeout": { "type": "integer", "description": "Command timeout in seconds", "minimum": 1, "maximum": 300, "default": 60 } }, "required": ["code"] } } ] }
- run.py:52-68 (schema)Input schema definition for the 'run_powershell' tool, specifying parameters 'code' (required string) and 'timeout' (optional integer)."inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "PowerShell code to execute" }, "timeout": { "type": "integer", "description": "Command timeout in seconds", "minimum": 1, "maximum": 300, "default": 60 } }, "required": ["code"] }