# How to Troubleshoot Full Disk Access Permissions on macOS for Desktop Commander

> Fix macOS Full Disk Access permission errors for Desktop Commander. Follow our guide to grant necessary permissions and resolve issues quickly.

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

---

**Desktop Commander detects macOS permission blocks through the `buildPermissionError` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) (lines 95‑105) and surfaces a built‑in guide that directs you to enable Full Disk Access for the application in System Settings or immediately open the privacy pane via the terminal command `open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"`.**

Desktop Commander (wonderwhy-er/DesktopCommanderMCP) requires deep file system integration to execute commands across your directories, which triggers macOS security protections that block unauthorized processes from accessing protected locations like Documents or Desktop. When the tool attempts to read files without the necessary privileges, the system intercepts the call and returns a permission denial that must be resolved through Full Disk Access permissions. Understanding how the [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) module handles these errors allows you to quickly diagnose and fix access issues without guessing which security settings to adjust.

## Why Full Disk Access Is Required for Desktop Commander

Desktop Commander accesses the file system through the **[`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)** module, which performs read and write operations on behalf of the AI layer. macOS Catalina and later versions restrict applications from accessing sensitive user data—such as files in Desktop, Documents, Downloads, and iCloud Drive—unless the user explicitly grants **Full Disk Access** in Privacy & Security settings. When Desktop Commander attempts to access these protected paths without authorization, the operating system returns a permission denial that the tool must catch and translate into actionable guidance.

## How Desktop Commander Detects and Reports Permission Errors

The codebase implements a two-layer permission strategy: platform detection for macOS-specific guidance and an allowed directories validation system.

### Platform-Specific Error Generation (buildPermissionError)

When a file read operation fails, the **`buildPermissionError`** function (located at lines 95‑105 in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)) checks the runtime platform using `process.platform === 'darwin'`. For macOS systems, it constructs a detailed error message containing:

- **Navigation instructions** to System Settings → Privacy & Security → Full Disk Access
- **The specific toggle** to enable (Desktop Commander or Claude, depending on how you run the tool)
- **A terminal shortcut** that opens the exact preferences pane instantly

If the platform is not macOS, the function falls back to a generic permission hint.

### Allowed Directories Validation (getAllowedDirs)

Before attempting file operations, Desktop Commander validates paths against an **allowed directories** list managed by `getAllowedDirs`. This function, supported by **[`src/config-manager.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.js)**, maintains a whitelist of safe paths and can detect other permission-related edge cases such as cloud storage folders or network drives. The Full Disk Access handling serves as one branch of this comprehensive permission-checking strategy, ensuring that users receive context-specific guidance based on exactly where the access failure occurred.

## Step-by-Step Guide to Granting Full Disk Access on macOS

Follow these steps to resolve permission denials when Desktop Commander cannot access your files:

1. **Trigger the error detection.** Attempt a file operation through Desktop Commander. If macOS blocks access, the tool will return an error message containing the specific guidance generated by `buildPermissionError`.

2. **Open Full Disk Access settings.** You have two options:
   - **Manual navigation:** Open System Settings → Privacy & Security → Full Disk Access
   - **Terminal shortcut:** Run the following command to jump directly to the correct pane:

   ```bash
   open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
   ```

3. **Enable the application toggle.** Locate **Desktop Commander** (or **Claude** if you are running the tool via the Claude desktop application) in the list and enable the toggle.

4. **Restart the application.** Fully quit and reopen Desktop Commander to ensure the new permissions take effect. The [`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts) utility ensures that subsequent file operations complete within timeout limits once access is granted.

## Handling Permission Denials in Your Integration Code

When building custom integrations with Desktop Commander, wrap file operations in try-catch blocks to capture the detailed error messages:

```typescript
import { readFile } from './tools/filesystem.js';

async function preview(filePath: string) {
  try {
    const content = await readFile(filePath);
    console.log(content);
  } catch (err: any) {
    // When macOS Full Disk Access is missing, err.message includes the guidance
    console.error('❗️ Permission issue:', err.message);
  }
}

```

The `err.message` will contain the macOS-specific instructions generated by the `buildPermissionError` function, allowing your application to surface the exact fix required without custom error handling logic.

## Summary

- **Error origin:** Desktop Commander generates permission guidance through `buildPermissionError` in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) (lines 95‑105) when `process.platform === 'darwin'` detects a macOS system.
- **Immediate fix:** Run `open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"` to open the Full Disk Access pane directly.
- **Validation layer:** The `getAllowedDirs` function and [`src/config-manager.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.js) provide additional path validation beyond basic macOS permissions.
- **Timeout protection:** File operations use [`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts) to prevent hanging when permissions are being resolved.

## Frequently Asked Questions

### What file contains the Full Disk Access error handling logic in Desktop Commander?

The logic resides in **[`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)** within the `buildPermissionError` function (lines 95‑105). This function specifically checks for macOS using `process.platform === 'darwin'` and constructs the error message that guides users to the correct System Settings pane.

### Why does Desktop Commander need Full Disk Access instead of regular file permissions?

Regular file permissions allow access only to specific user-selected files or non-restricted directories. Desktop Commander operates as a file system utility that must access protected macOS locations—such as Desktop, Documents, and application data folders—to execute comprehensive commands. **Full Disk Access** is the only macOS permission level that grants unfettered access to these sensitive paths without requiring explicit user approval for every single file operation.

### Can I automate the Full Disk Access grant via script?

No. Apple explicitly prevents applications from programmatically enabling Full Disk Access for security reasons. The `buildPermissionError` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) provides the `open` command shortcut precisely because manual user intervention is mandatory. You must physically toggle the permission in System Settings; scripts can only open the preference pane to streamline the manual step.

### What if I enabled Full Disk Access but still see permission errors?

First, verify that you enabled the correct application entry—if you run Desktop Commander through the Claude desktop app, you must enable **Claude** in the Full Disk Access list, not just the standalone Desktop Commander binary. Second, ensure you fully restarted the application after granting permissions, as macOS does not retroactively grant access to running processes. Finally, check that the target path is included in your `getAllowedDirs` whitelist defined in [`src/config-manager.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.js), as the tool separately validates paths against allowed directories before attempting system calls.