# How to Enable Non-Headless Mode for Debugging in xiaohongshu-mcp

> Debug xiaohongshu-mcp interactively by enabling non-headless mode. Launch with the -headless=false flag to see the Chrome browser window for easier troubleshooting.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: how-to-guide
- Published: 2026-03-09

---

**To enable non-headless mode in xiaohongshu-mcp, launch the binary with the `-headless=false` flag to display the Chrome browser window for interactive debugging.**

When automating Xiaohongshu (Little Red Book) interactions using the `xpzouying/xiaohongshu-mcp` project, the browser runs in headless mode by default to conserve resources. However, to troubleshoot selectors, verify page loads, or debug authentication flows, you need to enable non-headless mode for debugging in xiaohongshu-mcp to visualize the browser automation steps.

## Understanding the Headless Configuration Architecture

The headless behavior is controlled through a three-layer configuration system that propagates from command-line arguments to the browser factory.

At the entry point in [`main/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go) (lines 13-19), the application defines a boolean flag `-headless` with a default value of `true`. This flag is parsed and stored via `configs.InitHeadless(headless)` at line 26, which persists the setting in the global configuration state.

The [`configs/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go) file (lines 9-12) maintains the `useHeadless` variable and provides getter/setter functions. When the browser initializes, it queries this configuration to determine whether to launch Chrome with or without a visible window.

Finally, in [`browser/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go), the `NewBrowser` function receives the headless boolean and passes it directly to `headless_browser.WithHeadless(headless)` at line 45, which instantiates the Chrome DevTools Protocol (CDP) session with the specified visibility setting.

## Step-by-Step Guide to Enable Non-Headless Mode

### Using the Command-Line Flag

To switch from the default headless operation to a visible browser window for debugging, append the `-headless=false` flag when executing the binary.

```bash

# Default headless execution (no UI)

./xiaohongshu-mcp -headless=true

# Debug mode with visible Chrome window

./xiaohongshu-mcp -headless=false

```

If you are specifying a custom Chrome binary path, combine both flags:

```bash
./xiaohongshu-mcp -headless=false -bin=/usr/bin/google-chrome

```

### Verifying the Configuration at Runtime

When the application initializes, it logs the current headless state to confirm your flag was applied correctly. Look for log output indicating `headless: false` to verify that the browser will launch in visible mode.

## Alternative: Modifying the Default in Source Code

If you prefer not to pass flags during every execution, you can change the default value in the source before compiling. In [`main/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go), locate the `flag.BoolVar` declaration for the headless parameter and change the default from `true` to `false`:

```go
// Change this line in main/main.go
flag.BoolVar(&headless, "headless", false, "Run browser in headless mode")

```

After recompiling with `go build`, the binary will default to non-headless mode without requiring the flag.

## Summary

- **Use the `-headless=false` flag** to enable non-headless mode for debugging in xiaohongshu-mcp and display the Chrome browser window.
- The configuration flows from [`main/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go) through [`configs/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go) to [`browser/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go), where `headless_browser.WithHeadless()` receives the boolean parameter.
- Verify the setting through application logs that report the headless state at startup.
- For permanent changes, modify the default value in [`main/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go) before compilation.

## Frequently Asked Questions

### What is the default headless mode in xiaohongshu-mcp?

By default, xiaohongshu-mcp runs in headless mode (`-headless=true`) to minimize resource consumption and avoid displaying browser windows during automated operations. This default is defined in [`main/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go) at line 13 where the flag is initialized.

### Can I switch between headless and non-headless mode without recompiling?

Yes. The `-headless` flag is evaluated at runtime, allowing you to toggle between modes by simply changing the command-line argument when launching the binary. This design eliminates the need to modify source code or rebuild the application for debugging sessions.

### Why does the browser window close immediately when running in non-headless mode?

If the Chrome window appears briefly then disappears, the application is likely completing its automation task and calling the cleanup routine. To keep the window open for inspection, you would need to add a delay or breakpoint in the Go code, or modify the [`browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser.go) logic to pause before closing the CDP session.

### Does non-headless mode affect the MCP server functionality?

No, the MCP server functionality remains identical regardless of the headless setting. The only difference is the visibility of the browser window; all API endpoints, tool handlers, and automation logic execute the same way, making non-headless mode purely a debugging convenience.