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

> Understand how Desktop Commander MCP audit logging works. Learn where its rotating logs are stored in your home directory and how it streams JSON-RPC notifications.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-28

---

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

All internal modules route through the central `log()` function exported from [`src/utils/logger.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts))

The `FilteredStdioServerTransport` class defined in [`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

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

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

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.