# How to Configure allowedDirectories to Restrict Filesystem Access for DesktopCommanderMCP

> Learn how to configure allowedDirectories in DesktopCommanderMCP to restrict filesystem access. Whitelist specific paths or leave empty for unrestricted access.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-11

---

**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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-symlink-security.js).

```javascript
// 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)](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.
   ```javascript
   await configManager.setValue('allowedDirectories', [
     '~',
     '/opt/shared-data'
   ]);
   ```

2. **Restricted production**: Permit only the application workspace.
   ```javascript
   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)](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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-allowed-directories.js) and [`test/test-symlink-security.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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)](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)](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.