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

> Learn how to enable verbose logging in Chrome DevTools MCP. Set the DEBUG environment variable to mcp:* or * and use flags for detailed output. Troubleshoot with ease.

- Repository: [ChromeDevTools/chrome-devtools-mcp](https://github.com/chromedevtools/chrome-devtools-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/logger.ts) using the `debug` package with a fixed namespace.

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

```bash

# 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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts).

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

```

When `--logFile` is provided, the server invokes `saveLogsToFile` from [`src/logger.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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.

```typescript
// 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.

```typescript
// 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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/logger.ts) or [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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.