# DesktopCommanderMCP Process Management System: How list_processes and kill_process Work

> Explore DesktopCommanderMCP's process management system. Learn how list_processes and kill_process safely manage Windows and Unix-like systems.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-14

---

**DesktopCommanderMCP implements a two-layer process management system where handlers receive commands, tools execute OS-level operations, and schemas validate inputs to safely list and terminate processes across Windows and Unix-like systems.**

DesktopCommanderMCP is a Model Context Protocol (MCP) server that exposes desktop control functionality to AI assistants. Its **process management system**, which powers the `list_processes` and `kill_process` commands, follows a clean separation between command handlers and OS-level tool execution. This architecture ensures cross-platform compatibility while maintaining strict input validation through Zod schemas.

## Two-Layer Architecture

### Tool Layer

The **tool layer** in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) contains the core OS integration logic. The `listProcesses()` function executes platform-specific commands—`ps aux` on Unix-like systems and `tasklist` on Windows—using Node.js `child_process.exec` to capture process information. For termination, `killProcess()` accepts a validated Process ID (PID) and invokes Node's native `process.kill(pid)` method to send the termination signal.

### Handler Layer

The **handler layer** in [`src/handlers/process-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/process-handlers.ts) exposes these tools as command endpoints. `handleListProcesses()` acts as a thin wrapper that forwards requests directly to `listProcesses()`, while `handleKillProcess()` parses incoming arguments using `KillProcessArgsSchema` before delegating to `killProcess()`. This separation allows the handlers to focus on request routing while the tools handle OS-specific implementation details.

## Input Validation and Safety

The system validates all termination requests through `KillProcessArgsSchema` defined in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts). This Zod schema guarantees that only numeric `pid` values reach the OS-level kill operation, preventing malformed requests from causing errors or unintended behavior. The schema acts as a strict gatekeeper between the handler layer and the tool layer, ensuring that `process.kill()` receives valid arguments.

## Command Execution Flow

The process management system follows a strict **command-handler → tool → OS** flow:

1. A client issues `list_processes` or `kill_process` commands to the server
2. The request routes to the appropriate handler (`handleListProcesses` or `handleKillProcess`)
3. The handler calls the corresponding tool implementation (`listProcesses` or `killProcess`)
4. The tool executes the OS command (`ps aux`/`tasklist`) or invokes `process.kill`
5. Results wrap in a `ServerResult` object (defined in [`src/types.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/types.js)) and return to the client

## Implementation Examples

### Direct Tool Usage

For programmatic access to process management without the handler abstraction, import directly from the tools module:

```typescript
// List all running processes
import { listProcesses } from './src/tools/process.js';

listProcesses().then(res => console.log(res.content[0].text));

```

```typescript
// Terminate a specific process by PID
import { killProcess } from './src/tools/process.js';

killProcess({ pid: 1234 }).then(res => console.log(res.content[0].text));

```

### Handler-Based Execution

When integrating with the server's command router, use the handler functions which provide schema validation and standardized responses:

```typescript
import { handleListProcesses, handleKillProcess } from './src/handlers/process-handlers.ts';

// Retrieve process list
handleListProcesses().then(r => console.log(r.content[0].text));

// Kill process with PID 1234
handleKillProcess({ pid: 1234 }).then(r => console.log(r.content[0].text));

```

## Summary

- DesktopCommanderMCP uses a **two-layer architecture** separating handlers ([`src/handlers/process-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/process-handlers.ts)) from OS tools ([`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts))
- **Process listing** uses `child_process.exec` with platform-specific commands (`ps aux` on Unix, `tasklist` on Windows)
- **Process termination** validates PIDs through `KillProcessArgsSchema` before calling Node.js `process.kill(pid)`
- The **command flow** moves from client → handler → tool → OS, with results wrapped in `ServerResult` objects
- All process management operations return standardized responses defined in [`src/types.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/types.js)

## Frequently Asked Questions

### How does DesktopCommanderMCP list processes on different operating systems?

The system detects the platform and executes the appropriate command: `ps aux` for Unix-like systems (Linux, macOS) and `tasklist` for Windows. These commands run through Node.js `child_process.exec` in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts), capturing the output and returning it as formatted text within a `ServerResult` object.

### What safety measures prevent invalid process termination?

The `KillProcessArgsSchema` in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) validates that the `pid` parameter is strictly numeric before execution reaches the OS level. This schema validation occurs in `handleKillProcess()` before delegating to `killProcess()`, ensuring only properly formatted process IDs attempt termination via Node's `process.kill()` method.

### Can I use the process management tools without the handler layer?

Yes. The `listProcesses()` and `killProcess()` functions in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) export directly for use without handler overhead. However, using `handleListProcesses()` and `handleKillProcess()` from [`src/handlers/process-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/process-handlers.ts) provides automatic argument validation and standardized error handling through the `ServerResult` type.

### What information does list_processes return?

The `listProcesses()` function returns raw output from the system's process listing command (either `ps aux` or `tasklist`), wrapped in a `ServerResult` object with a text content block. This includes process IDs, memory usage, CPU time, and command-line information depending on the operating system.