DesktopCommanderMCP Process Management System: How list_processes and kill_process Work

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 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 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. 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) 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:

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

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

// 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:

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) from OS tools (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

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, 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 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 export directly for use without handler overhead. However, using handleListProcesses() and handleKillProcess() from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}