How Desktop Commander MCP Settings Persist Across Server Restarts

TLDR: Desktop Commander MCP persists settings across server restarts by storing configuration data in a JSON file located at ~/.claude-server-commander/config.json, managed by the singleton ConfigManager class.

Desktop Commander MCP ensures user preferences survive server restarts through a durable file-based persistence layer. According to the source code in the wonderwhy-er/DesktopCommanderMCP repository, the system leverages a dedicated configuration directory in the user's home folder and a singleton manager to handle all read and write operations atomically.

Where Settings Are Stored

All user-editable settings are serialized to a JSON file named config.json residing in a hidden directory inside the user's home folder. As defined in [src/config.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts), the configuration directory path is constructed using os.homedir() and stored in the CONFIG_DIR constant, specifically at ~/.claude-server-commander.

When the Node.js process terminates, data stored in this file survives because it lives on the filesystem, ensuring Desktop Commander MCP settings persist across server restarts automatically.

The ConfigManager Architecture

The persistence mechanism centers on the ConfigManager singleton implemented in [src/config-manager.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts). This class encapsulates all configuration logic and maintains an in-memory copy of settings to minimize disk I/O while guaranteeing durability.

Initialization and Default Configuration

When the server starts, ConfigManager.init() executes a three-step process:

1. Directory verification: It ensures CONFIG_DIR exists, creating it if necessary.
2. File loading: If config.json exists, the method reads the file via fs.readFile and parses the JSON content.
3. Default generation: If the file is missing, it generates a default configuration object via getDefaultConfig() and immediately persists it to disk using saveConfig().

This initialization sequence guarantees that a valid configuration object is always available in memory before the server accepts connections.

Read and Write Operations

All subsequent configuration access flows through the ConfigManager instance:

• Reading values: configManager.getValue(key) returns the requested setting from the in-memory object populated during initialization.
• Updating values: configManager.setValue(key, value) mutates the in-memory object and then calls saveConfig() to serialize the entire configuration back to CONFIG_FILE.
• Non-blocking updates: For high-frequency changes, setValueNonBlocking() coalesces rapid updates into a single background write, preventing race conditions and reducing filesystem overhead.

Practical Code Examples

The following patterns demonstrate how to interact with the persistence layer:

// Retrieve a specific setting (e.g., the default shell)
const defaultShell = await configManager.getValue('defaultShell');

// Persist a configuration change (e.g., disable telemetry)
await configManager.setValue('telemetryEnabled', false);

// Access the entire configuration object
const allSettings = await configManager.getConfig();

// Restore factory defaults (writes immediately to disk)
await configManager.resetConfig();

Key Files and Responsibilities

Understanding the separation of concerns helps when debugging persistence issues:

• [src/config.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config.ts): Defines the config directory path (~/.claude-server-commander) and the CONFIG_FILE constant pointing to config.json.
• [src/config-manager.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts): Implements the singleton ConfigManager class that handles loading, writing, and updating the configuration file.
• [README.md](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/README.md#configuration): Documents that settings persist between server restarts via the config.json file.

Summary

Desktop Commander MCP achieves durable configuration persistence through these key mechanisms:

• Settings serialize to a JSON file at ~/.claude-server-commander/config.json located in the user's home directory.
• The ConfigManager singleton in src/config-manager.ts manages all file I/O and maintains an in-memory cache.
• Initialization automatically creates default configurations if no file exists, ensuring the server always starts with valid settings.
• The setValueNonBlocking() method optimizes write performance for rapid successive updates.

Frequently Asked Questions

Where is the Desktop Commander MCP configuration file located?

The configuration file is stored at ~/.claude-server-commander/config.json on Unix-like systems (Linux, macOS) and the equivalent path inside the user's home directory on Windows. This path is generated dynamically in src/config.ts using the Node.js os.homedir() API.

What happens if the config.json file is deleted while the server is running?

If the file is deleted externally, the in-memory configuration remains active until the server restarts. However, on the next startup, ConfigManager.init() will detect the missing file and automatically regenerate default settings via getDefaultConfig(), writing a fresh config.json to disk.

How does ConfigManager handle rapid successive setting updates?

The class provides setValueNonBlocking(), which queues writes and executes them in the background, coalescing multiple rapid changes into a single disk operation. This prevents filesystem race conditions and improves performance when updating settings programmatically in tight loops.

Are Desktop Commander MCP settings encrypted at rest?

No, the settings are stored as plain JSON text without encryption. The config.json file contains human-readable key-value pairs, making it easy to manually edit or debug, but administrators should ensure proper filesystem permissions on the ~/.claude-server-commander directory to restrict unauthorized access.

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