DesktopCommanderMCP Logging Capabilities: Debug Modes, Console Output, and File Auditing

DesktopCommanderMCP provides a centralized, environment-configurable logging system that supports console-based debug output, standardized error prefixes, and file-based audit trails for specific operations like uninstallation.

The wonderwhy-er/DesktopCommanderMCP repository implements a lightweight yet comprehensive logging strategy across its TypeScript and JavaScript codebase. Understanding these logging capabilities is essential for debugging MCP (Model Context Protocol) tool executions, monitoring server health, and maintaining audit trails for lifecycle operations.

Centralized Logger Architecture

The logging infrastructure centers on a single exported instance defined in src/utils/logger.ts. This module exports a logger constant that standardizes formatting and behavior across the entire application, ensuring consistent output whether the server is running in production or development mode.

All operational modules import this centralized logger rather than implementing ad-hoc console logging. This design pattern guarantees uniform prefixing, error handling, and debug toggling throughout the DesktopCommanderMCP server.

Console Logging Features

Standard Output Prefixing

By default, the logger prefixes regular operational messages with "[Desktop Commander]". This visual marker allows users and automated log parsers to distinguish DesktopCommanderMCP output from other MCP servers or system processes running in the same terminal session.

import { logger } from '@/utils/logger';

// Outputs: "[Desktop Commander] Server initialized on port 3000"
logger.info('Server initialized on port 3000');

Debug Mode Configuration

When the environment variable DESKTOP_COMMANDER_DEBUG is set to a truthy value, the logger automatically switches to verbose debug mode. In this state, all log entries are prefixed with "[Desktop Commander Debug]" instead of the standard tag, making it easy to filter high-volume diagnostic output during troubleshooting.

# Enable debug logging before starting the server

export DESKTOP_COMMANDER_DEBUG=1
npx @wonderwhy-er/desktop-commander@latest

According to the source code in track-installation.js, this environment check allows developers to toggle verbosity without modifying source files or rebuilding the project.

Error Highlighting

Error-level logging receives special formatting to ensure visibility in dense log streams. When the logger processes an error condition, it prepends the "ERROR:" string to the message content, creating immediate visual distinction from informational logs.

// Outputs: "[Desktop Commander] ERROR: Failed to execute command"
logger.error('Failed to execute command', errorDetails);

File-Based Logging for Audit Trails

While console logging handles runtime diagnostics, certain lifecycle operations require persistent records. The uninstall-claude-server.js script implements a dedicated logToFile(message, isError) function that appends timestamped entries to setup.log in the installation directory.

This file-based approach ensures that uninstallation attempts and failures are recorded even if the console session terminates or stdout is redirected. The implementation uses synchronous file appending with ISO 8601 timestamps:

// From uninstall-claude-server.js
import { appendFileSync } from 'fs';
import { join } from 'path';

const LOG_FILE = join(__dirname, 'setup.log');

function logToFile(message, isError = false) {
  const timestamp = new Date().toISOString();
  const logMessage = `${timestamp} - ${isError ? 'ERROR: ' : ''}${message}\n`;
  appendFileSync(LOG_FILE, logMessage);
}

// Usage examples
logToFile('Starting Desktop Commander uninstallation...');
logToFile('Permission denied accessing config directory', true);

Each entry includes a full timestamp and error flag, creating a permanent audit trail for troubleshooting installation issues across system restarts.

Practical Implementation Examples

Basic Logger Usage Pattern

The standard import pattern used throughout the codebase looks like this:

import { logger } from '@/utils/logger';

// Informational logging
logger.info('Loaded configuration:', config);

// Debug logging (conditional on DESKTOP_COMMANDER_DEBUG)
logger.debug('Processing request:', requestId);

// Error reporting with structured data
logger.error('Command execution failed', {
  command: args.command,
  exitCode: result.code,
  stderr: result.stderr
});

Environment-Based Debug Activation

To enable verbose debugging for a single session without permanent configuration changes:

DESKTOP_COMMANDER_DEBUG=1 npm start

When active, the logger emits the debug prefix on every line, as implemented in the source files to assist with development workflows.

Persistent Logging in Custom Scripts

For operations requiring durable records beyond console output, implement a file logger similar to the uninstallation script:

import { appendFileSync } from 'fs';
import { join } from 'path';

const AUDIT_LOG = join(process.cwd(), 'audit.log');

function auditLog(operation, success, details = '') {
  const status = success ? 'SUCCESS' : 'FAILURE';
  const entry = `${new Date().toISOString()} [${status}] ${operation}: ${details}\n`;
  appendFileSync(AUDIT_LOG, entry);
}

Summary

• Centralized export: All modules consume the logger instance from src/utils/logger.ts for consistent behavior.
• Environment toggling: Set DESKTOP_COMMANDER_DEBUG=1 to enable verbose debug prefixing without code changes.
• Visual differentiation: Standard logs use "[Desktop Commander]", debug logs use "[Desktop Commander Debug]", and errors prepend "ERROR:".
• File persistence: The uninstallation flow in uninstall-claude-server.js demonstrates timestamped file logging to setup.log via the logToFile() helper.
• Audit trail support: Synchronous file appending ensures critical lifecycle events are captured even during process failures.

Frequently Asked Questions

How do I enable debug logging in DesktopCommanderMCP?

Set the environment variable DESKTOP_COMMANDER_DEBUG to any truthy value before starting the server. This activates the debug prefix "[Desktop Commander Debug]" on all log output, making it easy to distinguish verbose diagnostic information from standard operational logs.

Where is the logger implementation located in the source code?

The primary logging utility resides at src/utils/logger.ts, which exports a logger constant used throughout the application. Additional logging patterns, such as file-based auditing, appear in lifecycle scripts like uninstall-claude-server.js and track-installation.js.

Does DesktopCommanderMCP support writing logs to files?

Yes, though primarily through specific lifecycle scripts rather than the core logger. The uninstallation script implements logToFile(message, isError) to write timestamped entries to setup.log. The main server logger currently targets console output, with file redirection handled at the process level via standard shell operators.

What distinguishes error logs from standard output in DesktopCommanderMCP?

Error-level log entries are prefixed with "ERROR:" immediately following the standard "[Desktop Commander]" tag. This formatting ensures that failures stand out in dense terminal output or when piped to log aggregation systems.

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