How to Set Up Remote MCP to Use Desktop Commander from ChatGPT or Claude Web

Install the @desktop-commander/remote-device NPM package, authenticate with your device token, and run the tunnel CLI to bridge AI tool calls from ChatGPT or Claude Web to your local machine.

Desktop Commander (DC) exposes your local filesystem, terminal, and search capabilities to cloud-based LLMs through Remote MCP—a secure WebSocket tunnel that forwards tool calls from AI services to your computer without direct network exposure. This guide walks through the exact setup steps based on the wonderwhy-er/DesktopCommanderMCP source code.

---

How Remote MCP Works in Desktop Commander

The Remote MCP architecture separates three concerns: the AI service (ChatGPT/Claude Web), the cloud bridge (mcp.desktopcommander.app), and the local device running on your machine.

Key components:

Component	Location	Role
Remote MCP Cloud	https://mcp.desktopcommander.app	Receives tool calls from LLMs, routes to connected devices
Remote Device	Your local machine	Maintains authenticated WebSocket to cloud, executes requests
Desktop Commander Core	Bundled with device	Implements read_file, run_command, search operations
AI Service	OpenAI/Anthropic cloud	Issues tool calls via the configured MCP endpoint

All traffic uses TLS encryption. The local device only connects to the specific MCP URL you configure, and authentication requires a device token generated in the Desktop Commander web UI.

---

Prerequisites for Remote MCP Setup

Before installing, verify:

• Node.js ≥ 18 installed locally
• Active account at https://desktopcommander.app to generate device tokens
• ChatGPT (with plugin access) or Claude Web (with tool support) account
• Network access to mcp.desktopcommander.app (outbound HTTPS/WebSocket)

---

Step 1: Install the Remote Device CLI

The Remote Device package is published as @desktop-commander/remote-device. Install globally via NPM or use the official install script:

# Option A: NPM global install

npm i -g @desktop-commander/remote-device

# Option B: Official install script (downloads to ~/.desktop-commander/)

curl -fsSL https://mcp.desktopcommander.app/install.sh | bash

The install script places the binary at ~/.desktop-commander/desktop-commander-remote-device and adds it to your PATH.

Verify installation:

desktop-commander-remote-device --version

---

Step 2: Generate Your Device Token

Per the README.md in the repository root, device tokens are created through the Desktop Commander web interface:

1. Navigate to https://desktopcommander.app
2. Go to Settings → Remote Device
3. Click "Add New Device"
4. Copy the Device Token (base64-encoded string)

Store this token securely—it authenticates your specific machine to the Remote MCP service. The token is typically saved to ~/.desktop-commander/.mcp.json for CLI use.

---

Step 3: Start the Remote Device Tunnel

With your token, establish the WebSocket connection to the MCP cloud:

desktop-commander-remote-device \
  --token <YOUR_DEVICE_TOKEN> \
  --mcp-url https://mcp.desktopcommander.app \
  --log-level info

Expected output:

✅ Connected to Remote MCP – ready for AI calls
Device ID: dc-device-abc123
Tunnel: wss://mcp.desktopcommander.app/v1/tunnel/...

The device maintains a persistent connection with automatic reconnection. Keep this process running while using ChatGPT or Claude Web.

Production deployment (background service with PM2):

npm i -g pm2
pm2 start desktop-commander-remote-device -- \
  --token "$DC_TOKEN" \
  --mcp-url https://mcp.desktopcommander.app
pm2 save
pm2 startup

---

Step 4: Enable Desktop Commander in ChatGPT or Claude Web

ChatGPT Setup

1. Open ChatGPT (web or app)
2. Navigate to Settings → Beta Features → Plugins
3. Search for and enable Desktop Commander
4. The plugin automatically uses the Remote MCP endpoint—no additional configuration needed

Claude Web Setup

1. Open Claude at https://claude.ai
2. Go to Settings → AI Tools Setup
3. Enable Desktop Commander under available tools
4. Claude will route tool calls to https://mcp.desktopcommander.app

Both platforms now send tool invocations (like read_file, run_command) through the Remote MCP cloud to your active device tunnel.

---

Step 5: Issue Commands from AI Chat

With the tunnel active, simply prompt the AI naturally:

List all JavaScript files in my home directory, then read the package.json from the first result.

Behind the scenes, Claude or ChatGPT emits:

{
  "tool": "search",
  "arguments": {
    "pattern": "*.js",
    "path": "~",
    "max_results": 10
  }
}

The Remote MCP cloud receives this, routes to your connected device, which executes via Desktop Commander core and returns:

{
  "results": [
    "/Users/dev/project/server.js",
    "/Users/dev/project/utils.js"
  ]
}

The AI then automatically chains the next tool call:

{
  "tool": "read_file",
  "arguments": {
    "path": "/Users/dev/project/server.js",
    "limit": 50
  }
}

All execution happens on your machine; the AI only sees returned results.

---

Configuration File Reference

The Remote Device CLI reads defaults from ~/.desktop-commander/.mcp.json:

{
  "token": "your-device-token-here",
  "mcpUrl": "https://mcp.desktopcommander.app",
  "logLevel": "info",
  "reconnectInterval": 5000
}

Create this file to avoid passing --token on every startup.

---

Key Source Files in DesktopCommanderMCP

File	Purpose	Path
README.md	Overview of Remote AI Control for ChatGPT/Claude Web	wonderwhy-er/DesktopCommanderMCP/blob/main/README.md
src/remote-device/README.md	Detailed Remote Device architecture and troubleshooting	src/remote-device/README.md
package.json	Declares @desktop-commander/remote-device dependency	package.json
scripts/build-mcpb.cjs	Build script for Remote Device distribution binary	scripts/build-mcpb.cjs
skills/desktop-commander-overview/SKILL.md	LLM skill marketplace description	skills/desktop-commander-overview/SKILL.md

---

Troubleshooting Remote MCP Connections

Symptom	Cause	Fix
Connection refused	Token invalid or expired	Regenerate token in DC web UI
Tunnel timeout	Firewall blocking wss://	Verify outbound HTTPS (443) and WebSocket allowed
Device already connected	Duplicate process running	pkill -f desktop-commander-remote-device then restart
Command not found	PATH not updated	Use full path ~/.desktop-commander/desktop-commander-remote-device

Enable debug logging for detailed diagnostics:

desktop-commander-remote-device --token "$TOKEN" --log-level debug

---

Summary

• Remote MCP bridges cloud AI services to local Desktop Commander via encrypted WebSocket tunnel
• Install with npm i -g @desktop-commander/remote-device or the official install script
• Authenticate using a device token from desktopcommander.app Settings
• Run desktop-commander-remote-device --token <token> to establish the tunnel
• Enable the Desktop Commander skill in ChatGPT Plugins or Claude Web AI Tools
• All tool calls (read_file, run_command, search) execute locally, results return to AI

---

Frequently Asked Questions

What is the difference between Remote MCP and local MCP?

Local MCP runs Desktop Commander on localhost only, accessible to AI clients on the same machine. Remote MCP (via mcp.desktopcommander.app) allows ChatGPT and Claude Web—running in the cloud—to securely invoke tools on your computer through an authenticated tunnel. Remote MCP requires the Remote Device CLI; local MCP does not.

Can multiple devices connect with the same token?

No. Per the authentication flow in src/remote-device, each device token is bound to a single active connection. If you start a second device with the same token, the first connection is terminated. Generate separate tokens for each machine in the Desktop Commander web UI.

Is my filesystem exposed to the internet?

No. The Remote Device initiates an outbound-only WebSocket to mcp.desktopcommander.app. Your machine accepts no inbound connections. The cloud service cannot access your files without an active, authenticated device tunnel, and all traffic uses TLS 1.3 encryption.

How do I stop the Remote Device completely?

If running in the foreground, press Ctrl+C. For PM2-managed processes, run pm2 stop desktop-commander-remote-device or pm2 delete desktop-commander-remote-device. The tunnel closes immediately and Remote MCP stops forwarding calls for that device.

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