How to Manage Multiple DesktopCommanderMCP Instances: Complete Configuration Guide

You can run multiple DesktopCommanderMCP instances simultaneously by assigning each a unique port and separate configuration file, ensuring complete process isolation for different projects or AI contexts.

DesktopCommanderMCP is a Node.js-based MCP server that exposes file-system and shell automation tools to AI agents. Since it runs as a standard executable process, you can manage multiple DesktopCommanderMCP instances on the same machine by configuring distinct ports and isolated state directories. This guide walks through the exact configuration steps and source code locations necessary to deploy several independent servers side-by-side.

Understanding Process Isolation

Each DesktopCommanderMCP instance operates as an independent Node.js process with its own event loop, REPL sessions, and long-running shells. State such as opened shells, environment variables, and cached search results never leak between instances because they are stored in per-process memory structures.

According to the source code in [src/remote-device/desktop-commander-integration.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts), variables like activeSessions and searchManager exist only within the scope of a single process. This architectural isolation means you can safely run instances for different users, projects, or security contexts without cross-contamination.

Configuring Unique Ports and Settings

The server initialization logic in [src/server.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (approximately line 30) reads the listening port from config.port, defaulting to 3000 if unspecified. To manage multiple DesktopCommanderMCP instances, you must override this value for each additional server.

The configuration schema defined in [src/config-field-definitions.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-field-definitions.ts) supports distinct security boundaries per instance, including:

• allowedDirectories – Restricts file-system access to specific paths
• blockedCommands – Prevents execution of dangerous shell commands
• port – Defines the HTTP/WebSocket listening endpoint

Create separate configuration files for each instance to maintain these boundaries:

# Instance A configuration

cat > ~/.desktop-commander-a.json <<EOF
{
  "port": 3000,
  "allowedDirectories": ["/home/user/project-a"],
  "blockedCommands": ["rm -rf /", "dd if=/dev/zero"]
}
EOF

# Instance B configuration

cat > ~/.desktop-commander-b.json <<EOF
{
  "port": 3001,
  "allowedDirectories": ["/home/user/project-b"],
  "blockedCommands": ["rm -rf /"]
}
EOF

Deployment Strategies

You can deploy multiple instances using either native binaries or containerized environments. The repository includes helpers for both approaches in [src/utils/dockerPrompt.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/dockerPrompt.ts) and the scripts/ directory.

Native installation launches separate Node.js processes directly on the host:

npx @wonderwhy-er/desktop-commander start --config ~/.desktop-commander-a.json &
npx @wonderwhy-er/desktop-commander start --config ~/.desktop-commander-b.json &

Docker deployment maps each container to a different host port:

docker run -p 3000:3000 -v ~/.desktop-commander-a.json:/config.json wonderwhy-er/desktop-commander
docker run -p 3001:3000 -v ~/.desktop-commander-b.json:/config.json wonderwhy-er/desktop-commander

Connecting Remote-Device Bridges

The Remote Device component in [src/remote-device/device.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) connects a remote AI MCP to a specific local instance. When managing multiple DesktopCommanderMCP instances, start a remote-device process for each, pointing to the appropriate port:

# Connect to Instance A (default port)

npx @wonderwhy-er/desktop-commander-remote-device --url http://localhost:3000

# Connect to Instance B (port 3001)

npx @wonderwhy-er/desktop-commander-remote-device --url http://localhost:3001 --api-key <key>

Avoiding Port Collisions

Before launching instances dynamically, verify port availability. The helper script [scripts/ripgrep-wrapper.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js) contains logic for checking process availability that you can repurpose to generate random unused ports:

# Check if port 3002 is free before launching

if ! lsof -Pi :3002 -sTCP:LISTEN -t >/dev/null ; then
    npx @wonderwhy-er/desktop-commander start --port 3002 &
fi

Lifecycle Management and Graceful Shutdown

Stop specific instances by targeting their process ID or port pattern. The graceful shutdown logic in [src/remote-device/device.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) (approximately line 210) closes all active REPL sessions and releases resources before terminating:

# Stop only the instance on port 3001

pkill -f "desktop-commander.*--port 3001"

# Or use SIGTERM for graceful shutdown

kill -TERM <PID>

Verify instance status via the HTTP endpoint:

curl http://localhost:3000/status   # Returns: {"ready":true,"port":3000}

curl http://localhost:3001/status   # Returns: {"ready":true,"port":3001}

Summary

• Use separate configuration files for each instance to define distinct allowedDirectories and security policies
• Assign unique ports (default 3000) via the --port flag or config.port field to prevent binding conflicts
• Leverage process isolation through per-process memory structures (activeSessions, searchManager) that prevent state leakage between instances
• Deploy via native binaries or Docker containers, mapping each to different host ports when containerized
• Connect remote-device bridges to route AI agents to specific local instances by URL
• Implement graceful shutdown using SIGTERM to ensure all REPL sessions close properly before termination

Frequently Asked Questions

Can I run two DesktopCommanderMCP instances on the same port?

No. Each instance requires a unique port binding. The server initialization in src/server.ts will fail with an EADDRINUSE error if you attempt to start a second instance on an occupied port. Always specify distinct ports via --port or separate configuration files.

How do I prevent command history from leaking between instances?

Command history and shell state are automatically isolated because each instance maintains its own activeSessions map in memory. Since these data structures exist only within the Node.js process scope defined in src/remote-device/desktop-commander-integration.ts, no shared state persists between instances unless you explicitly configure external shared storage.

Is there a limit to how many instances I can run simultaneously?

The practical limit depends on your system's available ports (approximately 65,535 total, with ports below 1024 requiring root privileges) and memory capacity. Each DesktopCommanderMCP instance typically consumes minimal resources, but active shell sessions and large file search operations increase per-process memory usage. Monitor system resources when scaling beyond ten instances on a single machine.

How do I update configuration for a running instance?

You must restart the instance to reload configuration changes. Send a graceful shutdown signal to the specific instance using pkill -f "desktop-commander.*--port <PORT>", then relaunch with the updated configuration file. There is no hot-reload mechanism in the current implementation.

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