# How Desktop Commander MCP Provides AI Assistants with Secure File System Access

> Desktop Commander MCP grants AI assistants secure file system access via a three layer tool bridge. Explore paths, read/write files with timeouts and user-approved directory restrictions.

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

---

**Desktop Commander MCP exposes a three-layer tool bridge that lets AI assistants read, write, and explore the host file system through path-validated, timeout-protected operations restricted to user-approved directories.**

The Desktop Commander MCP repository implements a Model Context Protocol (MCP) server that transforms file system commands into safe, auditable tools for AI assistants. By combining a front-end bridge, server-side dispatchers, and security-validated handlers, the system enables powerful file operations while preventing unauthorized access to sensitive paths.

## The Three-Layer Tool Bridge Architecture

Desktop Commander MCP implements a **tool-bridge** pattern that connects AI assistants to host file operations through three distinct layers.

### Front-End Bridge (tool-bridge.ts)

The entry point resides in [`src/ui/shared/tool-bridge.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/shared/tool-bridge.ts), where the `createToolBridge` function constructs a `ToolBridge` instance. This bridge attempts host-specific helpers (`openai` or `mcp`) first, then falls back to a JSON-RPC postMessage protocol.

The `callTool` function iterates through available helpers and ultimately invokes `callViaFallback` to send `"tools/call"` messages when native integrations are unavailable:

```typescript
import { createToolBridge } from './ui/shared/tool-bridge.js';

const bridge = createToolBridge();
async function readExample() {
  const result = await bridge.callTool('read_file', {
    path: '~/notes/todo.txt',
    offset: 0,
    length: 200,
    origin: 'ui'
  });
  console.log(result);
}
readExample();

```

### Server-Side Dispatcher (server.ts)

The MCP server registers available file system tools in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 147-158), mapping tool names like `read_file` to their corresponding handler functions. When an AI assistant invokes a tool, the server routes the request to the appropriate handler:

- `read_file` → `handleReadFile`
- `write_file` → `handleWriteFile`
- `list_directory` → `handleListDirectory`

### File System Handlers (filesystem-handlers.ts)

Each handler lives in [`src/handlers/filesystem-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/filesystem-handlers.ts) and serves as the intermediary between the server dispatcher and the core file system API. These handlers receive validated parameters and delegate actual I/O operations to [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts).

## Security-First Path Validation

Before any file operation executes, Desktop Commander MCP performs rigorous path validation to prevent directory traversal and unauthorized access.

### Path Normalization and Symlink Resolution

The `validatePath` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) (lines 29-41 and 71-88) handles security-critical preprocessing:

- Expands `~` to the user's home directory
- Resolves symbolic links to their real paths
- Normalizes relative path segments

If a path resolves outside the permitted boundaries, the system throws a clear security error and captures a telemetry event for auditing.

### Allowed Directories Whitelist

Access control centers on the `allowedDirectories` configuration managed by [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts). By default, this whitelist contains only the user's home directory, meaning AI assistants cannot access system paths or other users' files without explicit permission.

The validation check occurs in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), where every requested path must fall within the configured whitelist before any read or write operation proceeds.

## Timeout-Protected I/O Operations

All file operations run inside **cancellable timeouts** to prevent hung I/O on remote or cloud-mounted paths. The `withTimeout` utility (sourced from [`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts)) wraps file operations—typically allowing 3 minutes for read operations before automatically aborting.

After validation, handlers call high-level APIs in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts):

- `readFile` chooses between local disk reads (`readFileFromDisk`) and URL fetches (`readFileFromUrl`)
- `writeFile` supports `rewrite` or `append` modes while capturing telemetry about file type, size, and line count

## Configuring Access Permissions

Administrators can expand the accessible directories at runtime using the `set_config` tool. This updates [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) through [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) (lines 84-92), allowing dynamic permission changes without restarting the server:

```typescript
await callTool('set_config', {
  key: 'allowedDirectories',
  value: ['/Users/alice/projects', '/tmp'],
  origin: 'assistant'
});

```

Subsequent file operations outside these paths are immediately rejected by the `validatePath` security layer.

## Summary

- Desktop Commander MCP provides file system access through a **three-layer architecture**: front-end bridge, server dispatcher, and handler layer.
- All paths undergo **strict validation** via `validatePath` in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), resolving symlinks and checking against `allowedDirectories`.
- Operations are **timeout-protected** (typically 3 minutes) using cancellable promises to prevent resource exhaustion.
- Access permissions are stored in [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) and managed by [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts), defaulting to the home directory only.
- The tool bridge supports multiple transport methods, falling back to JSON-RPC postMessage when native helpers are unavailable.

## Frequently Asked Questions

### How does Desktop Commander MCP prevent AI assistants from accessing sensitive system files?

Desktop Commander MCP implements a whitelist-based security model through the `allowedDirectories` configuration in [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts). The `validatePath` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) resolves and normalizes every path before access, throwing errors for any location outside the configured whitelist. By default, only the user's home directory is accessible, and all symlink traversal is resolved to prevent bypass attempts.

### What happens if a file read operation hangs or takes too long?

All file system operations are wrapped in cancellable timeouts via [`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts). Read operations typically timeout after 3 minutes, automatically aborting the request to prevent blocking the AI assistant or consuming excessive resources on network-mounted or cloud-backed storage systems.

### Can the AI assistant modify which directories it has access to?

Yes, but only through explicit user action. The `set_config` tool allows updating `allowedDirectories` at runtime via [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts), but this requires intentional invocation—typically by the user approving the change. The system does not allow the AI to escalate privileges automatically; directory access must be pre-configured or explicitly granted.

### Does Desktop Commander MCP support reading files from URLs or only local disk?

The `readFile` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) handles both protocols transparently. It detects HTTP/HTTPS URLs and routes them through `readFileFromUrl`, while local paths are processed by `readFileFromDisk`. This unified interface allows AI assistants to fetch remote resources and local files using the same `read_file` tool interface.