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

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 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
Tool Schemas	Zod validation and JSON-Schema generation	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
Configuration	Persistent settings and security policies	src/config.ts, src/config-manager.ts
Remote Device	Cloud gateway integration	src/remote-device/desktop-commander-integration.ts
Utilities	System detection, telemetry, onboarding	src/utils/system-info.ts, src/utils/capture.ts

---

Server Initialization and Client Detection

When the Node process starts, src/server.ts initializes the MCP server and gathers system context:

// 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, unless the client is identified as the Desktop Commander app itself or the disableOnboarding flag is set.

// 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
• Metadata – UI hints and A/B testing flags (_meta field)
• Annotations – Read-only hints, open-world hints for the client

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

---

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:

// 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 and validated in src/config.ts:

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

The capture() function in 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:

# 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

{
  "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

{
  "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:

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

Interact with process ID 42:

{
  "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:

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

Generate PDF from Markdown

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

  }
}

Recursive Directory Listing

{
  "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), tool implementations (src/tools/), UI resources (src/ui/), and configuration (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}