How to Configure Shell Detection and Selection for Desktop Commander MCP Across Windows, macOS, and Linux

Desktop Commander MCP automatically detects your operating system and selects PowerShell on Windows, zsh on macOS, or bash on Linux, while allowing manual overrides via configuration files or command parameters.

Desktop Commander MCP, an open-source Model Context Protocol server by wonderwhy-er, streamlines cross-platform shell operations by intelligently selecting the appropriate command interpreter for your environment. Understanding how to configure shell detection and selection for Desktop Commander MCP ensures your automated commands execute reliably across Windows, macOS, and Linux systems.

Automatic OS Detection and Default Shell Assignment

The automatic detection logic resides in src/utils/system-info.ts within the getSystemInfo() function (lines 15-46). This utility identifies the host platform using Node.js's os.platform() method and assigns a platform-appropriate default shell before exposing the configuration through the SystemInfo object.

The detection flow follows three distinct steps:

1. Identify the OS using os.platform() which returns win32, darwin, linux, or other Unix-like identifiers.
2. Assign the defaultShell through an conditional block that maps each platform to its preferred command interpreter.
3. Expose the value via the SystemInfo interface where defaultShell becomes available to the entire application stack.

Platform-Specific Shell Defaults

According to the source code in src/utils/system-info.ts, Desktop Commander MCP implements the following platform mappings:

• Windows: powershell.exe (with \ as the path separator)
• macOS: zsh (with / as the path separator)
• Linux: bash (with / as the path separator)
• Other Unix-like systems: bash (with / as the path separator)

When the application initializes, bootstrap.ts invokes getSystemInfo() and stores the resulting configuration globally, ensuring all subsequent subprocess launches utilize the detected default unless explicitly overridden.

Overriding the Default Shell Configuration

Users can bypass automatic detection through two primary override mechanisms implemented in the codebase.

Configuration File Method

The defaultShell field is formally declared in src/config-field-definitions.ts (lines 20-27), enabling users to specify a persistent custom shell through the MCP configuration. Create or modify your .mcp.json configuration file to set a preferred interpreter:

{
  "defaultShell": "cmd.exe"
}

This override takes precedence over OS detection and applies to all subsequent tool executions until the configuration is modified.

Command Parameter Method

For one-off executions, many tool commands accept a shell parameter that bypasses both the default detection and configuration file settings. The implementation in src/tools/improved-process-tools.ts (lines 157-159) reads this parameter and passes it directly to the underlying spawn or execFile calls:

import { runTool } from './tools/improved-process-tools';

// Forces Bash usage even on Windows systems
await runTool('git status', { shell: 'bash' });

This approach proves particularly useful when you need to execute Windows-specific batch commands via cmd.exe or utilize alternative Unix shells like fish or zsh on Linux/macOS systems.

Internal Detection Mechanisms

Beyond simple shell selection, Desktop Commander MCP implements sophisticated pattern recognition to handle interactive shell sessions appropriately.

REPL Prompt Pattern Recognition

The system recognizes when a spawned process enters an interactive read-eval-print loop (REPL) mode through pattern definitions in src/utils/process-detection.ts (lines 20-22). The REPL_PROMPTS.shell array contains regex patterns for common shell indicators including $, #, and % prompts, enabling the UI to maintain open connections when human input is expected.

OS-Specific Guidance Generation

The getOSSpecificGuidance() function in src/utils/system-info.ts (lines 632-652) generates contextual troubleshooting messages that incorporate the detected defaultShell. This ensures error messages and help text reference the correct command syntax for the user's specific platform, whether they're troubleshooting PowerShell execution policies on Windows or shell configuration issues on Unix systems.

Practical Implementation Examples

Reading the Detected Shell Programmatically

To inspect which shell Desktop Commander MCP has selected for your system:

import { getSystemInfo } from './utils/system-info';

const sysInfo = getSystemInfo();
console.log(`Default shell for this host: ${sysInfo.defaultShell}`);

Configuring the UI Shell Selector

The configuration editor interface in src/ui/config-editor/src/app.ts (lines 553-566) exposes a dropdown interface for shell selection:

// Excerpt from the configuration editor UI
options.add(
  `<select class="setting-inline-select" data-action="shell-select">
     <option value="powershell.exe">PowerShell</option>
     <option value="cmd.exe">CMD</option>
     <option value="bash">Bash</option>
   </select>`
);

Complete Configuration Override Workflow

When implementing custom shell logic in extensions or integrations:

// Configuration-driven shell selection
const config = {
  defaultShell: process.platform === 'win32' ? 'cmd.exe' : 'sh'
};

// Usage in process execution
await runTool('legacy-script.bat', { 
  shell: config.defaultShell 
});

Summary

• Desktop Commander MCP automatically selects powershell.exe on Windows, zsh on macOS, and bash on Linux through the getSystemInfo() function in src/utils/system-info.ts.
• Override mechanisms include the defaultShell configuration field (defined in src/config-field-definitions.ts) and per-command shell parameters (handled in src/tools/improved-process-tools.ts).
• Implementation details involve REPL prompt detection in src/utils/process-detection.ts and OS-specific guidance generation for platform-appropriate error messaging.
• Path separators automatically adjust between Windows (\) and Unix-like systems (/) based on the detected platform.

Frequently Asked Questions

What shells does Desktop Commander MCP support by default?

According to the source code in src/utils/system-info.ts, Desktop Commander MCP defaults to powershell.exe on Windows, zsh on macOS, and bash on Linux and other Unix-like systems. The system uses Node.js's os.platform() to determine the host OS and assigns the appropriate interpreter automatically during the bootstrap phase.

How do I force Desktop Commander MCP to use Command Prompt instead of PowerShell on Windows?

Create a .mcp.json configuration file in your project root or user directory and specify "defaultShell": "cmd.exe" to override the automatic PowerShell selection. Alternatively, pass the shell parameter directly in command invocations: await runTool('dir', { shell: 'cmd.exe' }).

Where is the shell detection logic implemented in the Desktop Commander MCP repository?

The primary detection logic resides in src/utils/system-info.ts (specifically lines 15-46 within the getSystemInfo() function), with the configuration field definition located in src/config-field-definitions.ts (lines 20-27). The runtime application of these settings occurs in src/tools/improved-process-tools.ts (lines 157-159) where shell parameters are processed before process spawning.

Can I use fish, zsh, or other alternative shells with Desktop Commander MCP?

Yes. While the system defaults to standard shells, you can configure any installed shell interpreter by setting the defaultShell value in your configuration file or passing it as a command parameter. The spawn and execFile calls in src/tools/improved-process-tools.ts accept any valid shell path, allowing you to use fish, zsh, sh, or custom shell binaries provided they exist in the system PATH.

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