How to Configure Allowed Directories in Desktop Commander MCP: A Complete Guide

Set the allowedDirectories array in ~/.claude-server-commander/config.json to whitelist which filesystem paths MCP file tools can access—use the set_config_value tool, edit the JSON directly, or configure through the built-in editor.

Desktop Commander MCP implements a path-based access control mechanism to restrict where file-operation tools can read and write data. The allowedDirectories setting serves as the security boundary for MCP-native file operations, independent of terminal command permissions. This guide explains how to configure, verify, and troubleshoot this whitelist according to the wonderwhy-er/DesktopCommanderMCP source code.

Understanding the Allowed Directories Mechanism

The allowedDirectories configuration defines a whitelist of filesystem paths that MCP tools like read_file, write_file, and list_directory are permitted to access. This restriction applies only to MCP file tools—not to terminal commands executed through the shell.

Where Configuration Is Stored

The runtime configuration lives in a per-user JSON file at a fixed location. In src/config.ts, the path is defined as:

// src/config.ts, lines 8-10
export const CONFIG_FILE = path.join(os.homedir(), '.claude-server-commander', 'config.json');

This path expands to ~/.claude-server-commander/config.json on all platforms.

In-Memory Representation

The ServerConfig interface in src/config-manager.ts declares the field type:

// src/config-manager.ts, lines 12-13
interface ServerConfig {
  allowedDirectories: string[];
  // ... other fields
}

When the configuration file does not exist, config-manager.ts generates a default with an empty array at line 182, granting unrestricted filesystem access:

// src/config-manager.ts, line 182
allowedDirectories: [], // Empty array means no restrictions

Methods to Configure Allowed Directories

You have three pathways to modify the allowedDirectories whitelist. Each ultimately writes to the same configuration file.

Method 1: Use the set_config_value MCP Tool

The set_config_value tool provides the safest, most validated approach. Implemented in src/tools/config.ts (lines 155-165), this tool normalizes array inputs, validates the configuration key, and persists changes atomically:

// Example: Set allowed directories from an MCP client
await callTool('set_config_value', {
  key: 'allowedDirectories',
  value: ['/Users/alice/projects', '/tmp/shared', '/var/www/html']
});

The tool handler performs type checking and calls ConfigManager.setValue to write the configuration, ensuring the JSON structure remains valid.

Method 2: Direct File Editing

Edit ~/.claude-server-commander/config.json directly with any text editor:

// ~/.claude-server-commander/config.json
{
  "blockedCommands": ["sudo", "fdisk", "dd"],
  "defaultShell": "/bin/bash",
  "allowedDirectories": [
    "/Users/alice/projects",
    "/var/www",
    "/tmp/shared"
  ],
  "telemetryEnabled": true,
  "fileWriteLineLimit": 50,
  "fileReadLineLimit": 1000
}

Restart the MCP server after manual edits to ensure the new configuration loads into memory.

Method 3: Built-In Configuration Editor

The Desktop Commander web client includes a configuration editor that invokes set_config_value internally. Changes made through this UI take effect immediately without requiring a server restart.

Verifying Your Configuration

Use the get_config tool to inspect the current runtime configuration:

// Verify allowedDirectories is active
const response = await callTool('get_config', {});
const config = JSON.parse(response.content[0].text);
console.log(config.allowedDirectories);
// Output: ['/Users/alice/projects', '/var/www', '/tmp/shared']

Runtime enforcement occurs during path resolution: file-operation tools expand the target path to its absolute, real form, then check membership against allowedDirectories. Symlinks are resolved before validation, preventing escape attacks through symbolic links.

Critical Configuration Nuances

Understanding these edge cases ensures your security model behaves as expected.

Empty Array Behavior

An allowedDirectories value of [] removes all restrictions, granting file tools the same access as the default uninitialized state. This is not a deny-all configuration—it is permit-all.

Tilde and Home Directory Expansion

Paths beginning with ~ are expanded to the user's home directory before storage. For example, ~/Documents becomes /home/alice/Documents or /Users/alice/Documents depending on platform. The test suite test-home-directory.js confirms this behavior.

Path Normalization

Both ~/mydir and ~/mydir/ are accepted; the runtime check normalizes trailing slashes during validation. Stored values preserve your original formatting.

Terminal Command Bypass

allowedDirectories does not restrict terminal commands. A command executed through the shell tool can access any path the host user has permissions for:

# This succeeds even if /etc is not in allowedDirectories

cat /etc/passwd

This architectural separation acknowledges that shell execution inherently provides full system access, making path restrictions meaningful only for MCP-native file operations.

Security Architecture and Limitations

The whitelist model addresses accidental or malicious file access through MCP tools, not comprehensive sandboxing. Key security characteristics include:

• Symlink resistance: Resolved paths are validated, preventing ~/allowed/link → /etc/shadow escapes
• No command sandboxing: Shell and execute tools operate outside allowedDirectories constraints
• Per-user scoping: Configuration resides in user home directories, not system-wide locations

The test/test-allowed-directories.js test suite validates these security semantics across edge cases.

Summary

• allowedDirectories controls filesystem access for MCP file tools only, stored in ~/.claude-server-commander/config.json
• Three configuration methods: set_config_value tool (safest), direct JSON editing, built-in UI editor
• Default empty array [] permits unrestricted access—security requires explicit path enumeration
• Tilde expansion occurs at write time; paths are stored as absolute values
• Terminal commands bypass the whitelist entirely—consider blockedCommands for shell restrictions

Frequently Asked Questions

What happens if allowedDirectories is empty or missing?

An empty array or absent configuration grants unrestricted filesystem access to MCP file tools. This is the default behavior when first installing Desktop Commander MCP. To restrict access, populate the array with at least one absolute path.

Can I use relative paths like ./project or ../data in allowedDirectories?

No. The runtime validation requires absolute paths after tilde expansion. Relative paths are rejected or treated as non-matching, causing file operations to fail with permission errors. Always specify full paths or tilde-prefixed home directory references.

Why can terminal commands still access files outside allowedDirectories?

The allowedDirectories mechanism intentionally applies only to MCP-native file tools (read_file, write_file, etc.). Terminal command execution delegates to the system shell, which inherently operates with the full permissions of the running user. To restrict shell behavior, use the separate blockedCommands configuration rather than allowedDirectories.

Does allowedDirectories prevent symlink-based directory traversal?

Yes. The enforcement logic resolves symbolic links to their real paths before whitelist checking. A symlink pointing from an allowed directory to a restricted location will fail validation, blocking the traversal attack vector demonstrated in test-symlink-security.js.

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