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

> Learn to configure allowedDirectories in Desktop Commander MCP to secure file access. Use the set_config_value tool or edit config.json directly. A complete guide.

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

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts), the path is defined as:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) declares the field type:

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

```

When the configuration file does not exist, [`config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config-manager.ts) generates a default with an empty array at line 182, granting **unrestricted filesystem access**:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/config.ts) (lines 155-165), this tool normalizes array inputs, validates the configuration key, and persists changes atomically:

```typescript
// 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:

```json
// ~/.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:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```bash

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