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

> Discover what DesktopCommanderMCP audit logging captures like command executions and errors and where logs are stored at $HOME/.desktop-commander/logs/audit.log.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/trackTools.ts) and [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```text
$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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/clear-fuzzy-logs.js) script periodically archives or removes old entries, while [`scripts/export-fuzzy-logs.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
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:

```typescript
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:

```bash
node scripts/export-fuzzy-logs.js

```

## Key Implementation Files

- **[`src/utils/logger.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/logger.ts)** — Central logger that formats audit entries as JSON-RPC notifications and handles transport layer integration.
- **[`src/utils/fuzzySearchLogger.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts)** — Specialized logger capturing fuzzy-search UI interactions as part of the audit trail.
- **[`src/utils/trackTools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/trackTools.ts)** — Records tool and plugin invocation events during sessions.
- **[`src/utils/system-info.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/system-info.ts)** — Gathers and logs system context including hardware and environment details.
- **[`scripts/clear-fuzzy-logs.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/clear-fuzzy-logs.js)** — Performs periodic cleanup and rotation of audit log files to manage disk usage.
- **[`scripts/export-fuzzy-logs.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.