How to Kill or Force Terminate a Process in Desktop Commander MCP

Desktop Commander MCP provides a built-in kill_process command that gracefully stops a running process by its PID and, when necessary, escalates to a hard kill.

The wonderwhy-er/DesktopCommanderMCP repository implements a robust process management interface that allows users to terminate running processes safely through the Model Context Protocol. The implementation leverages Node.js process signaling through a structured command schema, providing both graceful termination via SIGTERM and force-kill capabilities via SIGKILL. Whether you need to stop a runaway terminal session or terminate a specific background process, the MCP server handles validation, execution, and comprehensive error reporting through its dedicated toolchain.

How to Use the kill_process Command

The primary interface for terminating processes is the kill_process command, which is registered in the server's RPC layer and exposed through the MCP tool interface.

Command Registration and Schema Definition

The tool schema for process termination is defined in src/tools/schemas.ts, which specifies the expected arguments including the process ID (PID). This schema is then registered with the server in src/server.ts under the "kill_process" entry, making the command available to connected MCP clients. The registration links the command name to its handler function and argument validation schema.

Handler Routing

When a client invokes the command, the request is routed to src/handlers/process-handlers.ts. This handler receives the raw request object, validates the arguments against KillProcessArgsSchema using safe parsing, and forwards the cleaned data to the core implementation. This separation of concerns ensures that transport-layer logic remains distinct from business logic.

Core Implementation Architecture

The actual process termination logic resides in src/tools/process.ts, where the killProcess function orchestrates the operation with comprehensive validation and error handling.

The killProcess Function

The killProcess function validates incoming arguments using KillProcessArgsSchema.safeParse(args) before attempting termination. Upon successful validation, it executes process.kill(parsed.data.pid), which sends a SIGTERM signal by default. This allows the target process to perform cleanup operations before exiting gracefully.

// Core implementation (src/tools/process.ts)
export async function killProcess(args: unknown): Promise<ServerResult> {
  const parsed = KillProcessArgsSchema.safeParse(args);
  if (!parsed.success) {
    return {
      content: [{ type: "text", text: `Error: Invalid arguments for kill_process: ${parsed.error}` }],
    };
  }

  try {
    process.kill(parsed.data.pid);            // Graceful termination
    return { content: [{ type: "text", text: `Process ${parsed.data.pid} killed` }] };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Error: Failed to kill process: ${error instanceof Error ? error.message : String(error)}` }],
    };
  }
}

Validation and Error Handling

If the PID is invalid, the process does not exist, or the user lacks permission to terminate the process, the function catches the thrown error and returns a descriptive ServerResult containing the failure message. This ensures clients receive actionable feedback rather than silent failures or uncaught exceptions.

Force Termination Fallbacks

When graceful termination fails or when immediate cessation is required, Desktop Commander MCP implements fallback strategies using specific Unix signal codes.

Signal-Based Killing

In src/terminal-manager.ts and src/search-manager.ts, the codebase demonstrates advanced termination patterns using session.process.kill('SIGINT') for interrupt signals and session.process.kill('SIGKILL') for forceful termination. SIGKILL (-9) immediately terminates the process without allowing cleanup, making it suitable for unresponsive processes that ignore SIGTERM.

// Example: Force kill using SIGKILL pattern (as implemented in session managers)
session.process.kill('SIGKILL');

Administrative Controls

The src/utils/usageTracker.ts file includes a feature-flag check for a remote kill-switch, allowing administrators to disable the kill_process command globally. This safety mechanism ensures that process termination capabilities can be revoked in managed environments or when security policies require restricting execution control.

Complete Code Examples

To terminate a process from a client application connected to the Desktop Commander MCP server:

// Example: Kill a process with PID 12345 from the client side
await client.request('kill_process', { pid: 12345 });

The handler implementation that routes requests to the core logic:

// Inside a handler (process-handlers.ts)
export async function handleKillProcess(request: any) {
  const parsed = KillProcessArgsSchema.safeParse(request.args);
  if (!parsed.success) {
    return { error: `Invalid arguments: ${parsed.error}` };
  }
  return killProcess(parsed.data);
}

Summary

• Desktop Commander MCP exposes process termination through the kill_process command registered in src/server.ts and handled in src/handlers/process-handlers.ts
• The killProcess function in src/tools/process.ts validates input using KillProcessArgsSchema before executing process.kill() for graceful termination
• Signal-based fallbacks in src/terminal-manager.ts and src/search-manager.ts demonstrate SIGINT and SIGKILL patterns for force termination
• A remote kill-switch in src/utils/usageTracker.ts provides administrative control to disable the command globally
• All operations include comprehensive error handling that returns descriptive messages through the ServerResult interface

Frequently Asked Questions

How do I force kill a process instead of gracefully terminating it?

While the standard kill_process command uses the default SIGTERM signal, you can implement force termination by modifying the call to use process.kill(pid, 'SIGKILL') as demonstrated in the session managers. This immediately terminates the process without cleanup, which is useful for unresponsive processes that ignore graceful shutdown requests.

What happens if I try to kill a process that doesn't exist?

The killProcess function validates the PID against KillProcessArgsSchema before execution and wraps the process.kill() call in a try-catch block. If the PID is invalid or the process doesn't exist, Node.js throws an error that is caught and returned as a descriptive error message in the ServerResult content, preventing server crashes.

Can administrators disable the kill_process command?

Yes. According to the source code in src/utils/usageTracker.ts, the implementation includes a feature-flag check that acts as a remote kill-switch. Administrators can disable the command globally to prevent process termination in specific environments or during maintenance windows.

Where is the kill_process command registered in the server?

The command is registered in src/server.ts as part of the MCP tool schema definition, with its request handler defined in src/handlers/process-handlers.ts and the core termination logic located in src/tools/process.ts. The argument schema is declared in src/tools/schemas.ts.

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