# Remote MCP Access to Local Resources for ChatGPT and Claude: A Complete Technical Guide

> Unlock secure remote MCP access to local resources for ChatGPT and Claude. Control your filesystem and terminal with DesktopCommanderMCP. Get the complete technical guide.

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

---

**Desktop Commander MCP enables secure, OAuth-authenticated remote access to your local filesystem, terminal processes, and file-preview UI for any MCP-compatible client including Claude Desktop and ChatGPT.**

This guide explains how the [wonderwhy-er/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP) repository implements remote MCP access to local resources for ChatGPT and Claude through a lightweight Remote Device wrapper, secure cloud gateway, and comprehensive toolset for file manipulation and process execution.

---

## What Is Desktop Commander MCP?

Desktop Commander MCP is a **Model Context Protocol (MCP) server** that exposes your local machine's capabilities to AI assistants. Unlike traditional MCP implementations that require local client installation, this architecture supports **remote MCP access** through a cloud-hosted gateway, allowing ChatGPT, Claude Desktop, and other compatible clients to invoke tools on your machine from anywhere.

The server provides four categories of functionality:

- **Filesystem operations** – `read_file`, `write_file`, `edit_block`, `list_directory`
- **Process management** – `start_process`, `interact_with_process`, `read_process_output`
- **Document generation** – `write_pdf`, `write_docx`, `write_xlsx`
- **Rich UI previews** – Syntax-highlighted code, image rendering, markdown editing

All execution occurs under your user permissions, with configurable allowlists and comprehensive audit logging.

---

## Architecture Overview

The codebase separates concerns across seven distinct layers:

| Component | Purpose | Key File |
|-----------|---------|----------|
| **MCP Server Core** | Bootstrap, client onboarding, tool mediation | [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) |
| **Tool Schemas** | Zod validation and JSON-Schema generation | [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) |
| **Tool Implementations** | Business logic for each capability | `src/tools/*.ts` |
| **UI Resources** | HTML/JS bundles for previews and editors | [`src/ui/resources.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/resources.ts) |
| **Configuration** | Persistent settings and security policies | [`src/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts), [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) |
| **Remote Device** | Cloud gateway integration | [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) |
| **Utilities** | System detection, telemetry, onboarding | [`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/system-info.ts), [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts) |

---

## Server Initialization and Client Detection

When the Node process starts, [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) initializes the MCP server and gathers system context:

```typescript
// src/server.ts
const SYSTEM_INFO = getSystemInfo();
const OS_GUIDANCE = getOSSpecificGuidance(SYSTEM_INFO);
const DEV_TOOL_GUIDANCE = getDevelopmentToolGuidance(SYSTEM_INFO);

```

The `SYSTEM_INFO` object captures your operating system, shell paths, and development environment. This data feeds into **guidance strings** injected into every tool description, helping the AI construct valid commands for your specific platform.

During the **Initialize** request (`InitializeRequestSchema`), the server extracts `clientInfo` and stores it in `currentClient`. It triggers an onboarding flow for new users via [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts), unless the client is identified as the Desktop Commander app itself or the `disableOnboarding` flag is set.

```typescript
// src/server.ts – client onboarding logic
if (currentClient.name !== 'desktop-commander-app' && … && !(global as any).disableOnboarding) {
    await handleWelcomePageOnboarding(currentClient.name);
}

```

---

## Tool Registration and Conditional Inclusion

The server constructs the available tool list in the `ListToolsRequestSchema` handler. Each tool registration includes:

- **Name** – The RPC identifier (e.g., `read_file`, `start_process`)
- **Description** – Markdown documentation with platform-specific guidance
- **Input Schema** – Generated via `zodToJsonSchema()` from [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts)
- **Metadata** – UI hints and A/B testing flags (`_meta` field)
- **Annotations** – Read-only hints, open-world hints for the client

```typescript
// src/server.ts – tool registration example
{
    name: "read_file",
    description: `… ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`,
    inputSchema: zodToJsonSchema(ReadFileArgsSchema),
    _meta: buildUiToolMeta(FILE_PREVIEW_RESOURCE_URI, true, showMcpUiPreviews),
    annotations: { title: "Read File or URL", readOnlyHint: true, openWorldHint: true },
},

```

The `shouldIncludeTool()` helper filters tools per client. For example, the `give_feedback_to_desktop_commander` tool is hidden when the client *is* the Desktop Commander app, since self-feedback is redundant.

---

## Security Model and Remote Device Isolation

Desktop Commander MCP implements defense-in-depth for remote MCP access:

### Allowed Directories

All filesystem tools enforce the `config.allowedDirectories` array. If empty, the server grants unrestricted access—documented as a **dangerous** configuration. Path validation occurs before any file operation.

### Command Blocklist

The `blockedCommands` array prevents execution of dangerous shell commands. The `detectUnsupportedParams()` utility warns if a disallowed command is requested in `start_process` or `interact_with_process`.

### Remote Device Flag

When launched via the **Remote Device**, the environment variable `DC_REMOTE_DEVICE=true` signals remote MCP traffic. This flag:

- Disables client-side shortcuts that could bypass security checks
- Ensures all tool invocations route through the cloud gateway
- Maintains OAuth-authenticated session binding

### Audit Logging

Every tool call is written to rotating logs:

- **macOS/Linux**: `~/.claude-tool-call.log`
- **Windows**: `%USERPROFILE%\.claude-server-commander\claude_tool_call.log`

Logs include timestamps, tool names, sanitized arguments, and execution metrics. Opt-out via `"telemetryEnabled": false` in [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json).

---

## Process Management and Data Analysis

Interactive terminal sessions use three coordinated tools:

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `start_process` | Spawn REPLs or shell commands | `command`, `shell`, `verbose_timing` |
| `interact_with_process` | Send input to running process | `pid`, `input` |
| `read_process_output` | Read incremental output with pagination | `pid`, `offset`, `length` |

The tool description for `start_process` enforces a **critical security rule**:

> "CRITICAL RULE: For ANY local file work, ALWAYS use this tool + `interact_with_process`, NEVER use analysis/REPL tool."

This prevents AI assistants from using generic code analysis tools when they should invoke local filesystem operations through Desktop Commander MCP.

---

## File Preview UI and Markdown Editor

When `read_file` succeeds, the server returns a **resource URI** (`FILE_PREVIEW_RESOURCE_URI`). Claude Desktop renders this in a preview panel supporting:

- **Syntax highlighting** for code files
- **Inline images** (PNG, JPEG, GIF, WebP)
- **PDF and Office document** extraction (PDF, Excel, DOCX)
- **Markdown editor** with live preview, undo, and "Open in folder" actions

The UI components live in `src/ui/file-preview/*` and are served through the Resources endpoint. An A/B test flag (`shouldShowMcpUiPreviews`) controls rollout of new UI features.

Resource endpoints are registered early in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts):

```typescript
// src/server.ts – resource handlers
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
    resources: listUiResources(),
}));

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
    const { uri } = request.params;
    const response = await readUiResource(uri);
    // … response handling
});

```

---

## Configuration and Telemetry

Persistent settings are managed through [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) and validated in [`src/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts):

```json
{
  "allowedDirectories": ["/home/user/projects", "/data"],
  "blockedCommands": ["sudo", "rm -rf /"],
  "telemetryEnabled": true,
  "lineLimit": 1000
}

```

The `capture()` function in [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts) sends analytics to rotating log files (10 MiB maximum per file). Each capture includes:

- Host entrypoint (truncated)
- AI agent identifier
- Tool execution metrics
- System information

---

## Docker Installation Option

For complete isolation, the repository provides a **Docker-based installation** via [`install-docker.sh`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/install-docker.sh):

```bash

# Pulls mcp/desktop-commander:latest

# Mounts specified host directories

# Runs server in isolated container

```

Docker mode eliminates host OS risk while preserving the full toolset. The container mounts only explicitly allowed directories, providing additional sandboxing beyond the application-level allowlist.

---

## Practical Code Examples

### Reading a File with Pagination

```json
{
  "tool": "read_file",
  "arguments": {
    "filePath": "/Users/alice/projects/report.md",
    "offset": 0,
    "length": 20,
    "isUrl": false
  }
}

```

Use negative `offset` to fetch the tail of large log files.

### Surgical Text Replacement

```json
{
  "tool": "edit_block",
  "arguments": {
    "file_path": "/Users/alice/projects/app.js",
    "old_string": "console.log('old');",
    "new_string": "console.log('new');",
    "expected_replacements": 1
  }
}

```

### Python REPL for CSV Analysis

Start the process:

```json
{
  "tool": "start_process",
  "arguments": {
    "command": "python3 -i",
    "shell": "/bin/bash",
    "verbose_timing": true
  }
}

```

Interact with process ID `42`:

```json
{
  "tool": "interact_with_process",
  "arguments": {
    "pid": 42,
    "input": "import pandas as pd; df = pd.read_csv('/absolute/path/data.csv'); print(df.describe())"
  }
}

```

Read output:

```json
{
  "tool": "read_process_output",
  "arguments": {
    "pid": 42,
    "offset": 0,
    "length": 100
  }
}

```

### Generate PDF from Markdown

```json
{
  "tool": "write_pdf",
  "arguments": {
    "path": "analysis_2025_01.pdf",
    "content": "# Quarterly Report\n\n## Summary\n\n* Revenue ↑\n* Users ↑"

  }
}

```

### Recursive Directory Listing

```json
{
  "tool": "list_directory",
  "arguments": {
    "directoryPath": "/Users/alice/projects",
    "depth": 3
  }
}

```

Results cap at 100 items per subdirectory to prevent context overflow.

---

## Summary

- **Desktop Commander MCP** provides remote MCP access to local resources for ChatGPT and Claude through a secure, OAuth-authenticated gateway.
- The architecture separates **server core** ([`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)), **tool implementations** (`src/tools/`), **UI resources** (`src/ui/`), and **configuration** ([`src/config.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts)).
- **Security features** include directory allowlists, command blocklists, Remote Device isolation, and comprehensive audit logging.
- **Process management tools** (`start_process`, `interact_with_process`, `read_process_output`) enable interactive REPL sessions with pagination support.
- **Rich UI previews** support code highlighting, images, PDFs, and an integrated markdown editor served via MCP Resources.
- **Docker deployment** offers complete sandboxing for security-sensitive environments.

---

## Frequently Asked Questions

### How does the Remote Device enable access from ChatGPT?

The Remote Device is a lightweight Node script that launches the server with `DC_REMOTE_DEVICE=true` and forwards MCP traffic to a cloud-hosted gateway. This establishes a secure tunnel allowing ChatGPT or Claude Desktop to invoke local tools without direct network access to your machine. Authentication occurs via OAuth, and all traffic is encrypted in transit.

### What prevents unauthorized file access when using remote MCP?

Three mechanisms enforce boundaries: (1) the `allowedDirectories` configuration array restricts filesystem operations to specified paths, (2) the `blockedCommands` array prevents dangerous shell execution, and (3) the Remote Device flag disables client-side shortcuts that could bypass validation. Additionally, every tool call is logged to `~/.claude-tool-call.log` for audit review.

### Can I run Desktop Commander MCP in a container?

Yes. The [`install-docker.sh`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/install-docker.sh) script deploys the server inside a Docker container using the `mcp/desktop-commander:latest` image. This mounts only explicitly allowed host directories, providing hardware-level isolation from your host OS while maintaining full compatibility with the toolset and remote MCP protocols.

### What is the difference between `read_file` and process-based analysis?

The `read_file` tool provides direct, paginated access to local files with optional UI preview. Process-based analysis (`start_process`, `interact_with_process`) spawns interactive REPLs or shells for dynamic data manipulation. The server explicitly instructs AI clients to use file tools for local file work rather than generic analysis tools, ensuring proper permission checks and audit logging.