list_processes
Retrieve running processes with optional name filtering and sorting by CPU or memory usage. Get details like PID, memory, and status for system monitoring.
Instructions
List running processes with optional filtering and sorting.
This tool retrieves information about running processes on the system, including PID, name, CPU usage, memory usage, command line, and status. Results can be filtered by name, sorted by various criteria, and limited to a maximum number of results.
Args: name_filter: Filter processes by name (case-insensitive substring match). If None, return all processes. sort_by: Sort processes by: cpu (descending), memory (descending), pid (ascending), or name (ascending). Default: cpu. limit: Maximum number of processes to return. Default: 100, max: 1000. ctx: MCP context for logging (optional)
Returns: ListProcessesOutput with process list, total count, truncation flag, and retrieval time
Raises: SanitizedError: If process iteration fails
Security: - Handles permission errors gracefully (skips inaccessible processes) - No sensitive system information leaked in errors - Command lines are included but may be empty if access denied - Zombie and terminated processes handled without errors
Performance: - Uses psutil.process_iter() for efficient iteration - oneshot() context for batch info retrieval per process - Target: <2s for process list retrieval
Examples: >>> result = await list_processes() >>> print(result.total_count, "processes found") 245 processes found
>>> result = await list_processes(
... name_filter="python",
... sort_by=ProcessSortBy.MEMORY,
... limit=50
... )
>>> for proc in result.processes:
... print(f"{proc.name}: {proc.memory_mb}MB")
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| sort_by | No | cpu | |
| name_filter | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| processes | Yes | List of process information | |
| truncated | Yes | Whether results were truncated due to limit | |
| total_count | Yes | Total number of processes found (before limit applied) | |
| retrieval_time_ms | Yes | Time taken to retrieve process information in milliseconds |