How allowedDirectories Restricts File System Access in DesktopCommanderMCP

DesktopCommanderMCP enforces a whitelist of directories defined in allowedDirectories to restrict all file system operations to explicitly permitted paths, defaulting to unrestricted access only when the list is empty.

DesktopCommanderMCP is a Model Context Protocol (MCP) server that exposes file system operations to AI assistants. To prevent unauthorized access to sensitive host files, the server implements an allowedDirectories whitelist that acts as a mandatory security gate for every read, write, copy, move, and delete operation.

Configuration and Initialization

The whitelist is stored in the global configuration object managed by src/config-manager.ts. The allowedDirectories key accepts an array of absolute path strings that define the boundaries of permitted file system access.

According to the schema defined in src/config-field-definitions.ts, this field serves as a "permission list" that explicitly limits which directories the tool can interact with. When the server initializes in src/tools/filesystem.ts, it loads this array via getAllowedDirs(). If the configuration key is missing or the array is empty, the server treats the entire file system as accessible—a configuration explicitly flagged as high-risk in the source documentation.

Path Validation Logic

Every file system request routes through the isPathAllowed(path) function implemented in src/tools/filesystem.ts (lines 172-209). This routine normalizes both the requested path and each entry in the whitelist before performing security checks.

The validation follows this hierarchy:

1. Full access mode: Returns true immediately if the whitelist is empty or contains '/' (Unix root), or a Windows root like C:\ when running on that platform.
2. Exact match: Checks if the normalized request path equals an allowed directory.
3. Sub-directory check: Verifies if the request path is a descendant of any allowed directory using path traversal checks.

If none of these conditions match, the function throws an error indicating the path is disallowed.

Enforcement Across File Operations

All high-level file system handlers in src/handlers/filesystem-handlers.ts delegate to the validation routine before executing commands. This ensures consistent enforcement across operations such as reading files, writing content, copying assets, moving directories, and deleting entries.

When a disallowed path is detected, the API returns a structured error object constructed in src/tools/filesystem.ts (lines 291-298) that includes the offending path and the current whitelist count, providing clear debugging information without exposing the full directory list.

Security Implications of Allowed Directories

The allowedDirectories mechanism is designed to minimize attack surface. By maintaining a minimal whitelist, administrators ensure that even if the MCP server is compromised, the attacker cannot access files outside the explicitly permitted folders.

Critical security note: An empty allowedDirectories array triggers unrestricted file system access. The source code in src/config-field-definitions.ts explicitly warns that this configuration removes all sandboxing and should be avoided in production environments.

Practical Implementation Examples

The following patterns demonstrate how to interact with the whitelist programmatically.

Retrieve the current whitelist configuration:

import { getAllowedDirs } from './tools/filesystem';

const dirs = await getAllowedDirs();
console.log('Allowed directories:', dirs);
// Output: ['/home/user/projects', '/var/www']

Check a path before performing operations:

import { isPathAllowed } from './tools/filesystem';

const target = '/home/user/projects/my-app/src/index.ts';
if (await isPathAllowed(target)) {
  // Safe to proceed with read/write
}

Handle disallowed path errors:

import { readFile } from './tools/filesystem';

try {
  const data = await readFile('/etc/passwd');
} catch (e) {
  console.error(e.message);
  // → "Path not allowed: /etc/passwd. Must be within one of these directories: /home/user/projects, /var/www"
}

Update the whitelist at runtime:

import { configManager } from './config-manager';

await configManager.setValue('allowedDirectories', [
  ...await configManager.getValue('allowedDirectories'),
  '/opt/shared',
]);

Summary

• allowedDirectories is a whitelist array stored in src/config-manager.ts that defines permitted file system boundaries.
• The isPathAllowed() function in src/tools/filesystem.ts normalizes paths and validates them against the whitelist before any operation.
• An empty whitelist grants full file system access, which the source code explicitly marks as a security risk.
• All file system handlers in src/handlers/filesystem-handlers.ts enforce this validation consistently across read, write, copy, move, and delete operations.
• Disallowed access attempts generate descriptive errors including the rejected path and whitelist statistics.

Frequently Asked Questions

What happens if allowedDirectories is empty?

When the allowedDirectories array is empty or undefined, DesktopCommanderMCP defaults to unrestricted file system access. According to src/config-field-definitions.ts, this configuration is deliberately highlighted as risky because it removes all sandboxing protections and allows the server to read or modify any file the host user can access.

How does the server handle Windows drive letters in allowedDirectories?

The isPathAllowed() function in src/tools/filesystem.ts treats Windows root paths like C:\ as full-drive permissions when listed in the whitelist. The validation logic normalizes paths for the platform and checks if the requested path falls within the drive scope, similar to how it handles Unix root /.

Can allowedDirectories be modified without restarting the server?

Yes, the configuration is managed through configManager in src/config-manager.ts, which allows runtime updates via setValue(). Changes to allowedDirectories take effect immediately for subsequent file system operations without requiring a server restart, though existing operations in progress will use the whitelist state at their initiation.

Which file system operations are protected by allowedDirectories?

All operations implemented in src/handlers/filesystem-handlers.ts enforce the whitelist, including file reading, writing, appending, copying, moving, renaming, and directory deletion. Each handler calls the shared isPathAllowed() validation routine before executing the underlying file system command, ensuring uniform security policy enforcement.

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