Does Desktop Commander MCP Configuration Survive Server Restarts? A Technical Deep Dive

Desktop Commander MCP configuration persists across server restarts because it is stored in a JSON file at ~/.desktop-commander/config.json, with the only exception being Docker containers running without volume mounts.

The Desktop Commander MCP server, developed in the wonderwhy-er/DesktopCommanderMCP repository, implements a file-based persistence layer that ensures user settings remain intact between process restarts. Unlike in-memory-only configurations, this approach writes every change to disk using the host file system, making Desktop Commander MCP configuration durable across standard server shutdowns and reboots.

How Configuration Persistence Works

The architecture relies on a centralized configuration manager that synchronizes an in-memory cache with a persistent JSON file on the host machine.

Config File Location and Structure

According to src/config.ts, the configuration directory and file are defined at the module level:

import path from 'path';
import os from 'os';

export const CONFIG_DIR = path.join(os.homedir(), '.desktop-commander');
export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');

This places the configuration at ~/.desktop-commander/config.json on Linux/macOS or the equivalent user profile directory on Windows. The CONFIG_DIR is created automatically if it does not exist, ensuring the path is always available for writing.

Loading and Saving Mechanism

The ConfigManager class in src/config-manager.ts handles the lifecycle of the configuration data. On initialization, it reads CONFIG_FILE into memory. When values change, the manager writes the entire object back to disk:

• Loading: Performed once at startup via import { CONFIG_FILE } and file system reads
• Saving: Implemented in setValue and setValueNonBlocking methods
• Debouncing: Rapid successive updates are coalesced to prevent excessive disk I/O

The write operation uses fs.writeFile asynchronously, ensuring non-blocking persistence while maintaining durability. This means even if the server process crashes immediately after a configuration change, the file on disk contains the latest state.

When Configuration Does NOT Survive Restarts

There is one specific deployment scenario where Desktop Commander MCP configuration does not persist: containerized environments without volume mounts.

Docker Container Limitations

As implemented in src/utils/dockerPrompt.ts, the application detects when running in Docker gateway mode and explicitly warns users: "No folder mounting support – Your files won't persist between restarts".

If the container is started without a volume mounted to $HOME/.desktop-commander, the config file resides in the container's writable layer. When the container stops, this layer is discarded, and all configuration changes are lost. To ensure persistence in Docker, you must mount a host directory to the container's config path.

Practical Code Examples

The following examples demonstrate how to interact with the configuration system in user code:

Reading a Config Value

import { configManager } from './config-manager.js';

async function showTelemetrySetting() {
  const enabled = await configManager.getValue('telemetryEnabled');
  console.log('Telemetry is', enabled ? 'enabled' : 'disabled');
}
showTelemetrySetting();

Changing a Config Value

import { configManager } from './config-manager.js';

async function disableTelemetry() {
  await configManager.setValue('telemetryEnabled', false);
  console.log('Telemetry disabled – survives restarts');
}
disableTelemetry();

Checking for First Run

import { configManager } from './config-manager.js';

async function isFirstRun() {
  const first = await configManager.isFirstRun();
  console.log('First run?', first);
}
isFirstRun();

Summary

• Desktop Commander MCP configuration survives ordinary server restarts by persisting to ~/.desktop-commander/config.json as defined in src/config.ts.
• The ConfigManager class in src/config-manager.ts handles atomic loading, debounced writing, and caching of configuration values.
• Settings such as telemetryEnabled, pendingWelcomeOnboarding (from src/utils/welcome-onboarding.ts), and usage statistics (from src/utils/usageTracker.ts) are automatically restored when the server restarts.
• Configuration persistence fails only in Docker deployments that lack volume mounts for the config directory, as noted in src/utils/dockerPrompt.ts.

Frequently Asked Questions

Where is Desktop Commander MCP configuration stored?

The configuration is stored in a JSON file at ~/.desktop-commander/config.json on the host file system. The exact path is constructed in src/config.ts using path.join(os.homedir(), '.desktop-commander', 'config.json'), ensuring it resides in the user's home directory regardless of operating system.

Does Desktop Commander MCP configuration survive server restarts in Docker?

Configuration survives server restarts in Docker only if you mount a host volume to the container's config directory. Without a volume mount, the config file is written to the container's ephemeral writable layer and is lost when the container stops. The application warns users about this limitation in src/utils/dockerPrompt.ts.

How does the config manager handle concurrent updates?

The ConfigManager implements debounced writes through its setValueNonBlocking method. Rapid successive updates are coalesced into a single write operation, preventing file system thrashing while ensuring the final state is persisted to disk. The underlying implementation uses asynchronous fs.writeFile calls.

What settings are persisted across restarts?

All settings managed through configManager survive restarts, including but not limited to: telemetry preferences (telemetryEnabled), onboarding flags (pendingWelcomeOnboarding from src/utils/welcome-onboarding.ts), custom tool paths, and usage statistics tracked in src/utils/usageTracker.ts. Any value set via setValue() or setValueNonBlocking() is written to the JSON file and reloaded on the next server start.

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