DesktopCommanderMCP Audit Logging: What Gets Logged and Where Logs Are Stored

DesktopCommanderMCP captures structured JSON-RPC audit events—including command executions, tool usage, system context, and errors—and stores them in $HOME/.desktop-commander/logs/audit.log with automatic rotation and configurable export capabilities.

The wonderwhy-er/DesktopCommanderMCP repository implements a comprehensive audit logging subsystem that creates a complete, structured trail of all runtime activities. This system is designed to provide transparency and accountability by recording every significant interaction through the Model Context Protocol (MCP) transport layer. Understanding what data is captured and where it persists is essential for security auditing, debugging, and compliance monitoring.

What Information Is Logged by DesktopCommanderMCP

The audit system captures seven distinct categories of operational data, all emitted through the central logger in src/utils/logger.ts.

Command Execution Events

Every command invocation generates a detailed record containing the command name, full argument string, user-provided input, timestamp, execution duration, and exit status. These events are captured via logger.info and logger.debug calls within command handlers, providing a complete trace of shell interactions and their outcomes.

Tool and Plugin Usage

The system tracks which built-in tools or plugins are invoked during a session, including the tool version and feature-flag state. This telemetry is handled by logger.debug entries in src/utils/trackTools.ts and src/utils/toolHistory.ts, enabling usage analytics and debugging of tool-specific issues.

System Context and Environment

Upon initialization and during key operations, DesktopCommanderMCP logs system-level context including OS type, architecture, CPU information, memory statistics, sanitized environment variables, and current working directory. These entries originate from src/utils/system-info.ts via logger.info calls, providing crucial environmental data for reproducing issues.

User Interface Interactions

User selections in UI components—such as fuzzy-search selections and file-preview clicks—are recorded to understand user workflows. The specialized logger in src/utils/fuzzySearchLogger.ts emits these events using logger.debug, capturing interaction patterns without exposing sensitive file contents.

Error Handling and Security Events

All exceptions generate structured error records containing stack traces, error messages, and associated data payloads through logger.error calls in catch blocks across the codebase. Additionally, security-relevant events—including permission changes, startup-item enumeration, and hardware health checks (battery wear, etc.)—are logged as described in the Computer Health Check skill documentation.

Audit Metadata and Correlation IDs

Each log entry includes audit-specific metadata such as audit-ID, correlation ID, session identifiers, and request/response IDs for JSON-RPC messages. This metadata is embedded by the transport layer before persistence, enabling distributed tracing and log correlation across multiple sessions.

Log Format and Transport Mechanism

All audit entries are emitted as structured JSON-RPC notifications using the method notifications/message. The payload contains a level field (conforming to standard syslog levels) and a data field housing the actual audit information. This uniform JSON structure allows downstream consumers—such as the MCP UI or external log aggregators—to parse and analyze the audit trail programmatically.

Where DesktopCommanderMCP Audit Logs Are Stored

Default Log Location

Audit logs are written to a per-user log directory created automatically on first run:

$HOME/.desktop-commander/logs/audit.log

The directory $HOME/.desktop-commander/logs is initialized by the runtime if it does not exist, ensuring seamless first-time setup across macOS, Linux, and Windows platforms.

Log Rotation and Maintenance

Log rotation is handled by dedicated utility scripts to prevent unbounded file growth. The scripts/clear-fuzzy-logs.js script periodically archives or removes old entries, while scripts/export-fuzzy-logs.js supports manual export workflows. These scripts ensure the audit file size remains bounded while preserving historical data for analysis.

Docker and Custom Path Configuration

For Docker-based installations, logs are mounted to /root/.desktop-commander/logs inside the container, making them accessible via host volume mappings. Developers can redirect audit output to custom locations by setting the MCP_LOG_PATH environment variable before launching MCP; this override is respected by the initialization logic in src/utils/logger.ts.

Working with Audit Logs Programmatically

Logging a Command Execution

When implementing custom command handlers, use the central logger to emit audit-compliant entries:

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

export async function runMyCommand(args: string[]) {
  const start = Date.now();
  try {
    // … command logic …
    logger.info('Command executed', {
      command: 'my-command',
      args,
      user: process.env.USER,
      cwd: process.cwd(),
    });
  } catch (e) {
    logger.error('Command failed', { error: e });
    throw e;
  } finally {
    logger.debug('Execution duration', {
      command: 'my-command',
      durationMs: Date.now() - start,
    });
  }
}

Reading the Audit Log

Consume the structured log file programmatically for analysis or monitoring:

import { readFile } from 'fs/promises';
import path from 'path';

async function readAuditLog() {
  const logPath = path.join(
    process.env.HOME ?? '',
    '.desktop-commander',
    'logs',
    'audit.log'
  );
  const raw = await readFile(logPath, 'utf-8');
  const entries = raw
    .trim()
    .split('\n')
    .map(line => JSON.parse(line));
  console.table(entries);
}

Exporting Logs via CLI

Export the current audit log to a timestamped archive using the provided maintenance script:

node scripts/export-fuzzy-logs.js

Key Implementation Files

• src/utils/logger.ts — Central logger that formats audit entries as JSON-RPC notifications and handles transport layer integration.
• src/utils/fuzzySearchLogger.ts — Specialized logger capturing fuzzy-search UI interactions as part of the audit trail.
• src/utils/trackTools.ts — Records tool and plugin invocation events during sessions.
• src/utils/system-info.ts — Gathers and logs system context including hardware and environment details.
• scripts/clear-fuzzy-logs.js — Performs periodic cleanup and rotation of audit log files to manage disk usage.
• scripts/export-fuzzy-logs.js — Provides helper functionality for exporting audit logs to external systems.

Summary

• DesktopCommanderMCP captures seven categories of audit data: commands, tools, system context, UI actions, errors, security events, and metadata.
• Logs are stored as structured JSON-RPC notifications in $HOME/.desktop-commander/logs/audit.log.
• The rotation system (scripts/clear-fuzzy-logs.js) prevents unbounded growth while preserving audit history.
• Environment variable MCP_LOG_PATH allows customization of the log directory for containerized or specialized deployments.
• All logging flows through src/utils/logger.ts, ensuring consistent formatting and transport compatibility with MCP standards.

Frequently Asked Questions

What is the default location of DesktopCommanderMCP audit logs?

By default, DesktopCommanderMCP stores audit logs at $HOME/.desktop-commander/logs/audit.log. This per-user directory is created automatically the first time the application runs, ensuring logs are isolated between different user accounts on shared systems.

How does DesktopCommanderMCP handle log rotation?

Log rotation is managed by scripts/clear-fuzzy-logs.js, which periodically archives old entries and enforces file size limits to prevent disk exhaustion. Additionally, scripts/export-fuzzy-logs.js allows administrators to manually export logs for long-term archival or external analysis before rotation occurs.

Can I customize where audit logs are stored?

Yes. Set the MCP_LOG_PATH environment variable before launching DesktopCommanderMCP to redirect audit output to a custom directory. This configuration is respected by the logger initialization code in src/utils/logger.ts, making it suitable for Docker deployments or centralized logging architectures.

What format are the audit logs in?

DesktopCommanderMCP writes audit logs as line-delimited JSON (NDJSON), where each line represents a JSON-RPC notification with the method notifications/message. Each entry contains a level field (syslog severity) and a data field holding the structured audit payload, enabling straightforward parsing by log aggregation platforms.

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