get_processes
Retrieve detailed information about running processes on Windows systems, including CPU usage, memory consumption, and process names. Filter by process name, sort by resource usage, and monitor system performance for enterprise management and automation tasks.
Instructions
Get information about running processes.
Args:
name: Filter processes by name (supports wildcards)
top: Limit to top N processes
sort_by: Property to sort by (e.g., CPU, WorkingSet)
timeout: Command timeout in seconds (1-300, default 60)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| top | No | ||
| sort_by | No | ||
| timeout | No |
Input Schema (JSON Schema)
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"sort_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sort By"
},
"timeout": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": 60,
"title": "Timeout"
},
"top": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Top"
}
},
"type": "object"
}
Implementation Reference
- src/server.py:112-130 (handler)The handler function for the 'get_processes' MCP tool. It constructs a PowerShell 'Get-Process' command based on parameters, formats it for JSON output, and executes it via execute_powershell.@mcp.tool() async def get_processes(name: Optional[str] = None, top: Optional[int] = None, sort_by: Optional[str] = None, timeout: Optional[int] = 60) -> str: """Get information about running processes. Args: name: Filter processes by name (supports wildcards) top: Limit to top N processes sort_by: Property to sort by (e.g., CPU, WorkingSet) timeout: Command timeout in seconds (1-300, default 60) """ code = "Get-Process" if name: code = f"{code} -Name '{name}'" if sort_by: code = f"{code} | Sort-Object -Property {sort_by} -Descending" if top: code = f"{code} | Select-Object -First {top}" code = f"{code} | Select-Object Name, Id, CPU, WorkingSet, StartTime" return await execute_powershell(format_json_output(code), timeout)
- src/server.py:850-909 (helper)Helper function that validates and executes PowerShell code securely using asyncio subprocess, with timeout handling and error checking. Used by get_processes and other tools.async def execute_powershell(code: str, timeout: Optional[int] = 60, ctx: Optional[Context] = None) -> str: """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 """ # Validate timeout if not isinstance(timeout, int) or timeout < 1 or timeout > 300: raise ValueError("timeout must be between 1 and 300 seconds") # Validate code if not validate_powershell_code(code): raise ValueError("PowerShell code contains potentially dangerous commands") if ctx: await ctx.info("Validating PowerShell code...") # Create and run process if ctx: await ctx.info("Starting PowerShell process...") process = await asyncio.create_subprocess_exec( "powershell", "-NoProfile", # Don't load profiles "-NonInteractive", # No interactive prompts "-Command", code, stdout=subprocess.PIPE, stderr=subprocess.PIPE ) try: if ctx: await ctx.info("Executing command...") stdout, stderr = await asyncio.wait_for( process.communicate(), timeout=timeout ) except asyncio.TimeoutError: process.kill() if ctx: await ctx.error(f"Command timed out after {timeout} seconds") raise TimeoutError(f"Command timed out after {timeout} seconds") if process.returncode != 0: error_msg = stderr.decode() if stderr else "Command failed with no error output" if ctx: await ctx.error(f"PowerShell command failed: {error_msg}") raise RuntimeError(error_msg) result = stdout.decode() if stdout else "" if ctx: await ctx.info(f"Command completed successfully, returned {len(result)} characters") return result
- src/server.py:30-35 (helper)Helper function that appends '| ConvertTo-Json' to PowerShell code if missing, ensuring JSON output for MCP tools like get_processes.def format_json_output(code: str) -> str: """Add JSON formatting to PowerShell code if not present.""" if not code.strip().lower().endswith('| convertto-json'): code = f"{code} | ConvertTo-Json" return code
- src/server.py:112-130 (registration)The @mcp.tool() decorator registers the get_processes function as an MCP tool.@mcp.tool() async def get_processes(name: Optional[str] = None, top: Optional[int] = None, sort_by: Optional[str] = None, timeout: Optional[int] = 60) -> str: """Get information about running processes. Args: name: Filter processes by name (supports wildcards) top: Limit to top N processes sort_by: Property to sort by (e.g., CPU, WorkingSet) timeout: Command timeout in seconds (1-300, default 60) """ code = "Get-Process" if name: code = f"{code} -Name '{name}'" if sort_by: code = f"{code} | Sort-Object -Property {sort_by} -Descending" if top: code = f"{code} | Select-Object -First {top}" code = f"{code} | Select-Object Name, Id, CPU, WorkingSet, StartTime" return await execute_powershell(format_json_output(code), timeout)