How to Enable Verbose Logging in Chrome DevTools MCP: A Complete Guide

Enable verbose logging in Chrome DevTools MCP by setting the DEBUG environment variable to mcp:* or *, and optionally use the --logFile flag to persist output to disk.

The Chrome DevTools MCP server relies on the debug library for all internal diagnostics. Whether you are troubleshooting connection issues or filing detailed bug reports, understanding how to activate and capture verbose output is essential. This guide covers the exact environment variables, CLI flags, and programmatic APIs exposed in the ChromeDevTools/chrome-devtools-mcp repository.

Understanding the Logging Architecture

The server initializes its logger in src/logger.ts using the debug package with a fixed namespace.

// src/logger.ts
import debug from 'debug';
const mcpDebugNamespace = 'mcp:log';
export const logger = debug(mcpDebugNamespace);

All diagnostic output flows through this logger instance. The debug library suppresses output by default unless the DEBUG environment variable matches the namespace pattern. This design allows fine-grained control over verbosity without modifying source code.

Enable Verbose Logging via Environment Variables

To surface internal messages, set the DEBUG variable to a pattern that matches mcp:log.

• View only MCP logs: DEBUG=mcp:* or DEBUG=mcp:log
• View all debug namespaces (including dependencies): DEBUG=*

Run the server with the variable set in your shell:

# All debug output (verbosest option)

DEBUG=* npx chrome-devtools-mcp@latest

# MCP-specific logs only

DEBUG=mcp:* npx chrome-devtools-mcp@latest

The output appears on stderr with timestamps and the namespace prefix, formatted by the debug library.

Persisting Logs to a File

For debugging asynchronous issues or submitting bug reports, capture verbose output to a file using the --logFile CLI option defined in src/cli.ts.

DEBUG=* npx chrome-devtools-mcp@latest --logFile /tmp/mcp-debug.log

When --logFile is provided, the server invokes saveLogsToFile from src/logger.ts. This function overrides the default debug.log implementation to write every line to the specified file path in addition to the console.

// src/logger.ts
export function saveLogsToFile(filePath: string): void {
  // Redirects debug output to filePath
}

The file receives the same formatted output visible in the terminal, ensuring no diagnostic data is lost during long-running sessions.

Programmatic Configuration

When embedding the MCP server in another Node.js application, enable verbose logging before importing the server modules.

// Enable verbose logging programmatically
process.env.DEBUG = 'mcp:*'; // or '*' for everything

// Optional: capture to file
import { saveLogsToFile } from 'chrome-devtools-mcp/src/logger.js';
saveLogsToFile('./mcp-runtime.log');

// Now import and start the server
import { runServer } from 'chrome-devtools-mcp/src/main.js';
await runServer({ /* options */ });

Setting process.env.DEBUG must occur before the first import of src/logger.ts or src/main.ts, as the debug library evaluates the environment variable at initialization time.

Summary

• Chrome DevTools MCP uses the debug library with the namespace mcp:log for all internal logging.
• Set DEBUG=mcp:* (or DEBUG=*) to enable verbose output in the console.
• Use the --logFile <path> CLI flag to persist logs to disk for troubleshooting.
• Import saveLogsToFile from src/logger.ts when embedding the server programmatically to capture diagnostics to a file.

Frequently Asked Questions

What is the exact namespace used for Chrome DevTools MCP logs?

The server initializes the debug logger with the namespace mcp:log in src/logger.ts. To filter output specifically for this server, set DEBUG=mcp:log or DEBUG=mcp:* to include all MCP-related namespaces.

Can I enable verbose logging without using the command line?

Yes. When running the server programmatically, set process.env.DEBUG = 'mcp:*' before importing any modules from chrome-devtools-mcp. This activates verbose output for the current Node.js process without requiring shell environment variables.

Where are logs saved when using the --logFile option?

The --logFile option writes verbose output to the absolute or relative path you specify (e.g., --logFile ./logs/mcp.log). The file receives the same formatted content printed to the console, including timestamps and namespace prefixes, as handled by the saveLogsToFile function in src/logger.ts.

Does enabling verbose logging impact performance?

Verbose logging increases I/O overhead because the debug library formats and writes strings to stderr (and optionally to a file). For production use or high-frequency automation, limit DEBUG to specific namespaces (e.g., mcp:log rather than *) to reduce noise and CPU usage.

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