How to Configure allowedDirectories to Restrict Filesystem Access for DesktopCommanderMCP

Configure the allowedDirectories array via configManager.setValue to whitelist specific absolute paths, or leave it empty to allow unrestricted filesystem access.

The DesktopCommanderMCP server uses a configuration key called allowedDirectories to control every filesystem operation. This array defines which directories the MCP (Multi‑Channel Processor) server may read from or write to, functioning as a security boundary that prevents unauthorized access outside designated areas. When configured correctly, the server validates all file paths against this whitelist before executing any operation, ensuring that even symbolic links cannot escape the defined boundaries.

How the allowedDirectories Whitelist Works

When the server receives a filesystem request—such as fs.readFile or fs.writeFile—it triggers an internal path-validation routine. This routine resolves the target path to its real-path using fs.realpath, then checks whether that resolved location falls inside at least one entry of the allowedDirectories array. If the path fails this check, the operation is immediately rejected with a "not allowed" error.

According to the DesktopCommanderMCP source code, this validation logic is exercised extensively in the test suite, which serves as the de-facto documentation for the whitelist mechanism. The validation occurs at the runtime level, driven by the Config Manager component accessed via configManager.setValue.

Setting Up Directory Restrictions

The allowedDirectories array accepts absolute paths or tilde-expanded shortcuts. Each entry represents a permitted zone, and the server grants access only when the resolved target lies within at least one zone.

Permitting Unrestricted Access

If allowedDirectories is omitted or set to an empty array, the validation step is bypassed entirely. This configuration grants the server access to any location on the host filesystem, as demonstrated in the "empty allowedDirectories" test case.

// Allow full filesystem access (default behavior)
await configManager.setValue('allowedDirectories', []);

Restricting to Specific Directories

Provide absolute paths to create a strict whitelist. The server will reject any operation targeting locations outside these directories.

// Restrict to two specific project folders
await configManager.setValue('allowedDirectories', [
  '/home/alice/projects',
  '/var/www/static'
]);

Using Tilde Expansion for Home Directories

The server recognizes a leading ~ as the current user’s home directory. It expands this shortcut to the absolute home path before validation, treating it like any other whitelist entry. The home-directory test validates this behavior.

// Permit only the user's home directory
await configManager.setValue('allowedDirectories', ['~']);

Allowing System Root Access

Adding the system root (/ on Unix systems) to the whitelist expands the accessible area to the entire filesystem while maintaining the validation framework. The root-directory test confirms this broadens the allowed paths without disabling the validation logic itself.

// Allow everything under "/"
await configManager.setValue('allowedDirectories', ['/']);

Security Features and Edge Cases

The DesktopCommanderMCP implementation includes specific protections against common path traversal and symlink attacks.

Symlink Protection and Path Resolution

Even if a symlink appears inside an allowed directory, the server resolves the target path before checking the whitelist. Therefore, a symlink pointing outside the allowed area is blocked, while one pointing to another allowed location is permitted. This security guarantee is illustrated in [test/test-symlink-security.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-symlink-security.js).

// Example: Attempting to read through a symlink outside allowed directories
try {
  const data = await fileHandler.readFile('/etc/passwd');
  // Throws because '/etc/passwd' is not inside any allowed directory
} catch (err) {
  console.error('Access denied:', err.message);
}

Trailing Slash Normalization

Paths ending with a forward slash are normalized before comparison. The server treats /my/dir and /my/dir/ as equivalent entries, ensuring consistent behavior regardless of how paths are entered. The specific-directory-with-slash test in [test/test-allowed-directories.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-allowed-directories.js) demonstrates this normalization.

Configuration Examples in Context

The following patterns from the test suite illustrate practical implementations:

1. Development environment: Allow the home directory plus a shared data folder.

   await configManager.setValue('allowedDirectories', [
     '~',
     '/opt/shared-data'
   ]);

2. Restricted production: Permit only the application workspace.

   await configManager.setValue('allowedDirectories', [
     '/var/www/app'
   ]);

3. Directory creation: When creating new directories via the server, the parent path must already reside within the whitelist, as shown in [test/test-directory-creation.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-directory-creation.js).

Summary

• allowedDirectories acts as a filesystem whitelist for the DesktopCommanderMCP server.
• An empty array or omitted key grants unrestricted access to the entire host filesystem.
• Paths are resolved to their real-path using fs.realpath before validation, with tilde (~) expansion supported for home directories.
• Symlinks are resolved before whitelist checking, preventing escape attempts via symbolic links.
• Trailing slashes are normalized, making /path and /path/ equivalent.
• Validation is enforced by the Config Manager and tested in files including test/test-allowed-directories.js and test/test-symlink-security.js.

Frequently Asked Questions

What happens if allowedDirectories is empty or omitted?

The server bypasses the path-validation routine entirely, granting unrestricted filesystem access. This behavior is demonstrated in the "empty allowedDirectories" test case within [test/test-allowed-directories.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-allowed-directories.js).

How does tilde (~) expansion work in allowedDirectories?

The server expands a leading ~ character to the current user’s absolute home directory path before performing whitelist checks. This allows portable configurations that work across different user accounts without hardcoding full paths.

Can symlinks bypass the allowedDirectories restrictions?

No. The server resolves symlinks to their target paths using fs.realpath before validating against the whitelist. A symlink pointing outside an allowed directory is blocked, while one pointing inside remains permitted. This protection is verified in [test/test-symlink-security.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-symlink-security.js).

How do trailing slashes affect directory matching?

Trailing slashes are normalized during the validation process. The server treats /my/dir and /my/dir/ as identical entries, so both forms are accepted when checking if a target path falls within an allowed directory.

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