mcollard0/mcp_chrome_spy

MCP Chrome Spy Server

An MCP (Model Context Protocol) server that monitors Chrome developer console logs using the Chrome DevTools Protocol.

Features

• Real-time console log monitoring via Chrome DevTools Protocol
• Tab selection - Choose which Chrome tab to monitor
• Log filtering - Filter by log level (verbose, info, warning, error)
• Incremental logging - Option to only return new logs since last request
• Configurable port - Support for custom Chrome remote debugging ports
• MCP integration - Works seamlessly with MCP-compatible AI agents

Installation

1. Install the required dependencies:

pip install -r requirements.txt

2. Make the server executable:

chmod +x chrome_spy_server.py

Chrome Setup

Before using the server, you need to start Chrome with remote debugging enabled:

# Linux/Mac
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

Usage

Running the Server

Start the MCP server with default settings:

python chrome_spy_server.py

Or with custom options:

python chrome_spy_server.py --remote-debugging-port 9223 --only-new-logs

Command Line Options

• --remote-debugging-port, -rdp: Chrome remote debugging port (default: 9222)
• --only-new-logs: Only return new logs since last request

MCP Tools Available

Once connected to an MCP client, the following tools are available:

1. list_chrome_tabs - Lists all available Chrome tabs with their IDs and URLs
2. select_chrome_tab - Selects a specific tab to monitor by tab ID
3. get_console_logs - Retrieves console logs from the selected tab
   • filter_level: Minimum log level (verbose, info, warning, error)
   • limit: Maximum number of entries to return (1-1000)
4. start_log_monitoring - Starts real-time log monitoring
5. stop_log_monitoring - Stops real-time log monitoring

Example Workflow

1. Start Chrome with debugging enabled
2. Start the MCP server
3. Connect your MCP client to the server
4. Use list_chrome_tabs to see available tabs
5. Use select_chrome_tab with a tab ID to choose which tab to monitor
6. Use get_console_logs to retrieve console logs
7. Optionally use start_log_monitoring for real-time updates

Architecture

The server consists of several key components:

• ChromeSpyServer: Main class handling MCP protocol and Chrome integration
• Chrome DevTools Protocol Integration: WebSocket connection to Chrome for real-time log events
• Tab Management: Discovery and selection of Chrome tabs
• Log Processing: Filtering, formatting, and delivering console logs
• MCP Protocol Handler: Standard MCP server implementation

Error Handling

The server includes comprehensive error handling for:

• Chrome not running or not accessible
• Network connection issues
• WebSocket connection failures
• Invalid tab selections
• Log processing errors

Backup System

The server automatically creates a backup/ directory for any necessary backups during operation.

Development

The code follows Python best practices with:

• Proper async/await patterns
• Type hints throughout
• Comprehensive error handling
• Clear separation of concerns
• Following user's coding style preferences (spaces in brackets, semicolons, long lines)

Troubleshooting

Chrome Not Found

• Ensure Chrome is running with --remote-debugging-port=9222
• Check that the port matches the one specified to the server
• Verify no firewall is blocking the connection

No Tabs Listed

• Make sure you have actual web pages open in Chrome (not just chrome:// URLs)
• Refresh the tab list if tabs were opened after starting the server

Connection Issues

• Check Chrome's remote debugging is still enabled
• Verify the WebSocket connection isn't being blocked
• Try restarting both Chrome and the server

Console Log Collection Issues

• Chatty websites: Some websites (like Microsoft.com, complex SPAs) generate hundreds of console messages per second
• This can delay Chrome DevTools Protocol command responses
• For testing, try simpler pages like http://example.com or local HTML files
• The server includes timeout handling for very active console output
• Consider using --only-new-logs flag to reduce message volume

Performance Notes

• The server is optimized for real-world usage with busy web applications
• Memory usage is controlled (max 1000 log entries stored)
• WebSocket connections are properly managed and cleaned up
• Command timeouts are set to handle very active pages (30+ seconds)

License

This project is open source and available under standard terms.