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

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 (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 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, 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.

# 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:

./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, locate the flag.BoolVar declaration for the headless parameter and change the default from true to false:

// 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 through configs/browser.go to 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 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 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 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.

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