Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
95 lines (60 loc) · 2.79 KB

TROUBLESHOOTING.md

File metadata and controls

95 lines (60 loc) · 2.79 KB

🚀 Installation and Connection Issues

Quick Diagnosis

Run the diagnostic tool to identify common issues:

mcp-chrome-bridge doctor

To automatically fix common issues:

mcp-chrome-bridge doctor --fix

Export Report for GitHub Issues

If you need to open an issue, export a diagnostic report:

# Print Markdown report to terminal (copy/paste into GitHub Issue)
mcp-chrome-bridge report

# Write to a file
mcp-chrome-bridge report --output mcp-report.md

# Copy directly to clipboard
mcp-chrome-bridge report --copy

By default, usernames, paths, and tokens are redacted. Use --no-redact if you're comfortable sharing full paths.

If Connection Fails After Clicking the Connect Button on the Extension

  1. Run the diagnostic tool first
mcp-chrome-bridge doctor

This will check installation, manifest, permissions, and Node.js path.

  1. Check if mcp-chrome-bridge is installed successfully, ensure it's globally installed
mcp-chrome-bridge -V
Screenshot 2025-06-11 15 09 57
  1. Check if the manifest file is in the correct directory

Windows path: C:\Users\xxx\AppData\Roaming\Google\Chrome\NativeMessagingHosts

Mac path: /Users/xxx/Library/Application\ Support/Google/Chrome/NativeMessagingHosts

If the npm package is installed correctly, a file named com.chromemcp.nativehost.json should be generated in this directory

  1. Check logs Logs are now stored in user-writable directories:
  • macOS: ~/Library/Logs/mcp-chrome-bridge/
  • Windows: %LOCALAPPDATA%\mcp-chrome-bridge\logs\
  • Linux: ~/.local/state/mcp-chrome-bridge/logs/
Screenshot 2025-06-11 15 09 41
  1. Check if you have execution permissions You need to check your installation path (if unclear, open the manifest file in step 2, the path field shows the installation directory). For example, if the Mac installation path is as follows:

xxx/node_modules/mcp-chrome-bridge/dist/run_host.sh

Check if this script has execution permissions. Run to fix:

mcp-chrome-bridge fix-permissions
  1. Node.js not found If you use a Node version manager (nvm, volta, asdf, fnm), the wrapper script may not find Node.js. Set the CHROME_MCP_NODE_PATH environment variable:
export CHROME_MCP_NODE_PATH=/path/to/your/node

Or run mcp-chrome-bridge doctor --fix to write the current Node path.

Log Locations

Wrapper logs are now stored in user-writable locations:

  • macOS: ~/Library/Logs/mcp-chrome-bridge/
  • Windows: %LOCALAPPDATA%\mcp-chrome-bridge\logs\
  • Linux: ~/.local/state/mcp-chrome-bridge/logs/