DesktopCommander MCP Security Model: How allowedDirectories and Blocked Commands Protect Your System

DesktopCommander MCP secures the host system through a dual-layer security model that restricts file-system access to whitelisted directories via allowedDirectories and blocks dangerous terminal commands via blockedCommands, with both policies enforced at runtime by the ConfigManager and CommandManager.

The wonderwhy-er/DesktopCommanderMCP repository implements a strictly enforced sandbox for AI-driven terminal interactions. This security architecture ensures that file operations and shell commands are validated against user-configurable policies before execution, preventing unauthorized data access and destructive system operations.

Allowed Directories: Filesystem Access Control

The allowedDirectories configuration array functions as a path-based whitelist that limits all filesystem operations to specified absolute paths. When this array contains entries, every read, write, and stat operation undergoes validation through the isPathAllowed(path) function.

According to the source code in src/config-manager.ts, the validation logic resolves real paths, expands tilde (~) shortcuts to home directories, and verifies that the target path is a descendant of at least one whitelisted entry. If the check fails, the system throws an AccessDenied error and terminates the operation. Configuring allowedDirectories as an empty array completely disables the whitelist, granting unrestricted filesystem access.

Blocked Commands: Terminal Execution Restrictions

The blockedCommands array acts as a blacklist for dangerous shell utilities such as sudo, rm, or iptables. Located in src/command-manager.ts (lines 231-251), the blocking logic parses user input into individual commands and extracts base commands from complex pipelines.

Before spawning any child process, the isCommandAllowed(baseCommand) method checks if the extracted command exists in the blockedCommands array. If detected, the REPL returns a "blocked by configuration" error and prevents process execution. The UI component in src/ui/config-editor/src/app.ts (lines 310-320) provides real-time visualization of currently blocked commands and counts.

Configuration and Runtime Enforcement

Security policies are loaded at startup when the ConfigManager class reads the central config.json file. The enforcement flow follows three distinct stages:

1. Path Validation: Filesystem functions invoke isPathAllowed() to verify the target path against allowedDirectories.
2. Command Parsing: The CommandManager deconstructs command pipelines and validates each component against blockedCommands.
3. Error Handling: Violations trigger immediate errors with descriptive messages describing the specific restriction encountered.

Both security lists support dynamic runtime modification without requiring an application restart, enabling temporary privilege elevation or emergency lockdown scenarios.

Practical Configuration Examples

Restrict all file operations to a single project directory:

await configManager.setValue('allowedDirectories', ['/home/user/projects']);

Attempting to access /etc/passwd after this configuration produces:

Error: Access to "/etc/passwd" denied – not within allowedDirectories

Block dangerous system administration commands:

await configManager.setValue('blockedCommands', ['sudo', 'rm', 'iptables', 'dd']);

A user entering sudo apt update receives:

Command "sudo" is blocked by configuration.

Temporarily disable all restrictions:

await configManager.setValue('allowedDirectories', []);  // Full filesystem access
await configManager.setValue('blockedCommands', []);     // No command blocks

Testing and Validation Coverage

The repository includes comprehensive test suites that verify security enforcement across edge cases. The test/test-allowed-directories.js file validates empty configurations, root directory restrictions, home path expansions, and trailing slash handling. The test/test-blocked-commands.js suite confirms that harmless commands execute normally while blocked entries are rejected, and verifies that runtime list updates take effect immediately.

Additional documentation regarding the high-level security architecture is available in the SECURITY.md file at the repository root.

Summary

• Dual-layer protection: DesktopCommander MCP combines directory whitelisting (allowedDirectories) with command blacklisting (blockedCommands) to create a sandboxed terminal environment.
• Path resolution: The isPathAllowed() function in src/config-manager.ts performs real path resolution and tilde expansion before validating filesystem access.
• Pipeline parsing: The CommandManager at src/command-manager.ts extracts and validates individual commands from complex shell pipelines against the blockedCommands list.
• Runtime flexibility: Both security arrays support dynamic modification via configManager.setValue(), allowing temporary privilege changes without application restarts.
• Explicit failure modes: Access violations generate clear error messages ("not within allowedDirectories" or "blocked by configuration") rather than silent failures.

Frequently Asked Questions

What happens when allowedDirectories is set to an empty array?

An empty allowedDirectories array disables the path whitelist entirely, granting the REPL full read and write access to the entire filesystem. This configuration effectively removes directory-based restrictions while maintaining active command blocking if blockedCommands remains populated.

How does DesktopCommander MCP handle command pipelines containing blocked commands?

The CommandManager parses complex shell pipelines and extracts base commands from each segment. If any command within the pipeline—including sub-commands or chained operations—appears in the blockedCommands array, the entire execution plan is rejected with a "blocked by configuration" error before any process spawns.

Can security settings be modified without restarting the application?

Yes, both allowedDirectories and blockedCommands support runtime updates through the ConfigManager class. Changes made via configManager.setValue() take effect immediately for subsequent operations, enabling dynamic security policy adjustments without terminating active sessions.

Where are the blocked command restrictions defined and enforced?

Command restrictions are defined in the user-configurable config.json file and enforced within src/command-manager.ts at lines 231-251. The UI representation in src/ui/config-editor/src/app.ts (lines 310-320) displays the current block list status, while validation logic resides in src/config-manager.ts.

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