https://github.com/mcollard0/mcp_chrome_spy
MCP Server for Chrome Developer Console Log monitoring via Chrome DevTools Protocol
https://github.com/mcollard0/mcp_chrome_spy
ai chrome debugging google mcp mcp-server python
Last synced: about 2 months ago
JSON representation
MCP Server for Chrome Developer Console Log monitoring via Chrome DevTools Protocol
- Host: GitHub
- URL: https://github.com/mcollard0/mcp_chrome_spy
- Owner: mcollard0
- Created: 2025-09-20T10:26:22.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-20T12:03:31.000Z (9 months ago)
- Last Synced: 2025-11-05T11:07:53.542Z (8 months ago)
- Topics: ai, chrome, debugging, google, mcp, mcp-server, python
- Language: Python
- Homepage:
- Size: 31.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```bash
pip install -r requirements.txt
```
2. Make the server executable:
```bash
chmod +x chrome_spy_server.py
```
## Chrome Setup
Before using the server, you need to start Chrome with remote debugging enabled:
```bash
# 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:
```bash
python chrome_spy_server.py
```
Or with custom options:
```bash
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.