How Desktop Commander MCP Audit Logging Works and Where Logs Are Stored

Desktop Commander MCP records every tool call to a rotating audit log in your home directory while simultaneously streaming structured JSON-RPC notifications to the MCP client.

Desktop Commander MCP implements a comprehensive audit logging system that captures every AI tool invocation against your host system. According to the wonderwhy-er/DesktopCommanderMCP source code, this dual-layer architecture ensures that operations are persisted locally for debugging and compliance while also being transmitted to clients like Claude Desktop for their own audit trails.

Core Architecture of the Audit Logging System

The logging pipeline consists of three coordinated layers that guarantee no operation goes unrecorded.

Central Logger Module (src/utils/logger.ts)

All internal modules route through the central log() function exported from src/utils/logger.ts. This utility aggregates log entries and forwards them to the global MCP transport instance. The logger attaches a standard name—desktop-commander—to every entry, along with timestamps and structured metadata objects.

MCP Transport Layer (src/custom-stdio.ts)

The FilteredStdioServerTransport class defined in src/custom-stdio.ts implements the actual transmission logic. Its sendLog() method constructs JSON-RPC notifications/message payloads and writes them to process.stdout. This ensures that MCP clients receive real-time audit notifications. The transport is instantiated in src/index.ts and attached to the global scope as global.mcpTransport, enabling any module to emit audit notifications.

File-Based Persistence and Rotation

In parallel to stdout streaming, the transport writes every log entry to a dedicated directory on the host machine:

• Audit log: <HOME>/.claude-server-commander-logs/audit.log
• Fuzzy-search log: <HOME>/.claude-server-commander-logs/fuzzy-search.log

Both files are created automatically on first write and follow a strict 10 MiB rotation policy. When a log exceeds this size, the system rotates it automatically, preventing unbounded disk usage.

Specialized Fuzzy-Search Logging

Beyond the general audit trail, fuzzy-search operations maintain their own isolated log channel. The src/utils/fuzzySearchLogger.ts module manages a separate tab-separated log file (fuzzy-search.log) using its own rotation logic. This separation allows developers to query search-specific history without parsing the general audit stream.

Practical Implementation Examples

Developers can interact with the logging system at different levels of abstraction.

Logging from Application Modules

Import the central logger to record errors or informational events with structured context:

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

// Example: logging a permission denied error
logger.error('Failed to read file', { path: '/etc/passwd', errno: 13 });

Sending Direct MCP Notifications

For custom instrumentation, access the global transport directly to emit audit entries:

declare global {
  var mcpTransport: FilteredStdioServerTransport | undefined;
}

// Emit a custom audit notification
if (global.mcpTransport) {
  global.mcpTransport.sendLog(
    'info',
    'User invoked the "search" tool',
    { query: 'TODO', scope: '/src' }
  );
}

Querying Fuzzy-Search History

Retrieve recent search operations programmatically using the dedicated fuzzy-search logger:

import { fuzzySearchLogger } from '../dist/utils/fuzzySearchLogger.js';

const recent = await fuzzySearchLogger.getRecentLogs(20);
console.log('Last 20 fuzzy-search entries:', recent);

This pattern is used by the CLI helper script scripts/view-fuzzy-logs.js to display search history.

Summary

Desktop Commander MCP audit logging guarantees complete visibility into AI-driven system operations through these key mechanisms:

• Dual-write architecture: Every log entry flows to both process.stdout (for MCP clients) and local rotating files (for persistent storage)
• Automatic rotation: Log files rotate at 10 MiB to prevent disk exhaustion
• Dedicated channels: Separate log streams for general audit events (audit.log) and fuzzy-search operations (fuzzy-search.log)
• Global accessibility: The FilteredStdioServerTransport instance is mounted on global.mcpTransport, enabling any module to emit audit notifications

Frequently Asked Questions

Where exactly are Desktop Commander MCP audit logs stored?

Audit logs are stored in a dedicated directory within your home folder: <HOME>/.claude-server-commander-logs/. The main audit trail resides in audit.log, while fuzzy-search operations are recorded separately in fuzzy-search.log. Both paths are created automatically when the server first writes a log entry.

What is the maximum size of log files before rotation?

Log files rotate automatically when they exceed 10 MiB. This limit is hardcoded in the transport layer to ensure that long-running Desktop Commander MCP instances do not consume excessive disk space, while still maintaining a substantive history of recent operations.

Which operations are captured in the audit trail?

The system records every tool call that the AI makes against the host system. This includes file reads and writes, process launches, directory traversals, and search operations. Each entry includes a timestamp, log level, the desktop-commander logger name, and structured metadata about the specific operation.

Can I read the fuzzy-search logs programmatically?

Yes. Import fuzzySearchLogger from src/utils/fuzzySearchLogger.ts and call getRecentLogs(n) to retrieve the last n entries. This API returns parsed log data suitable for building admin dashboards or debugging search functionality within your Desktop Commander MCP extensions.

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