Browser History Analysis MCP

# Browser History MCP Server [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://github.com/yourusername/browser-mcp-server) A local Model Context Protocol (MCP) server that provides access to browser history data for comprehensive analysis and insights. Built using the [official python MCP sdk](https://github.com/modelcontextprotocol/python-sdk), this tool can be added to Claude desktop in a few minutes using the [Quick Start](#-quick-start) guide. ## 📋 Table of Contents - [Features](#-features) - [Quick Start](#-quick-start) - [Installation](#-detailed-installation) - [Configuration](#-configuration) - [API Reference](#-api-reference) - [Browser Support](#-browser-support) - [Troubleshooting](#-troubleshooting) - [Privacy & Security](#-privacy--security) - [License](#-license) ## ✨ Features - 🔍 **Multi-Browser Support**: Query Firefox, Chrome, and (some versions of) Safari browser history - 📊 **Session Analysis**: Group browsing sessions with intelligent time-based clustering - 🏷️ **Smart Categorization**: Automatically categorize websites by type and purpose - 📈 **Domain Analytics**: Analyze domain frequency and visit patterns - 🎯 **Learning Insights**: Identify learning patterns and educational content consumption - ⚡ **Productivity Metrics**: Calculate productivity scores and distraction analysis - 🔄 **Real-time Access**: Direct database access for immediate insights - 🛡️ **Privacy-First**: Local processing with no data transmission ## 🚀 Quick Start 1. **Install `uv` for dependency management**: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh uv sync ``` 2. **Test locally**: ```bash uv run mcp dev server/main.py ``` 3. **Install for Claude Desktop** (you will need to restart Claude Desktop afterwards): ```bash uv run mcp install server/main.py --name "Browser History MCP" ``` ## 📦 Detailed installation ### Prerequisites - Python 3.12 or higher - Firefox, Chrome, or Safari browser - [uv](https://github.com/astral-sh/uv) (recommended) or pip ### Using uv (Recommended) ```bash # Install uv if you haven't already curl -LsSf https://astral.sh/uv/install.sh | sh # Clone and install git clone https://github.com/yourusername/browser-mcp-server.git cd browser-mcp-server uv sync ``` ### Using pip ```bash git clone https://github.com/yourusername/browser-mcp-server.git cd browser-mcp-server pip install -e . ``` ## ⚙️ Configuration ### Automatic Setup (Recommended) The server automatically detects your browser profile directories: | OS | Firefox Path | Chrome Path | |---|---|---| | **macOS** | `~/Library/Application Support/Firefox/Profiles/[profile-id].default-release` | `~/Library/Application Support/Google/Chrome/Default` | | **Linux** | `~/.mozilla/firefox/[profile-id].default-release` | `~/.config/google-chrome/Default` | | **Windows** | `%APPDATA%\Mozilla\Firefox\Profiles\[profile-id].default-release` | `%LOCALAPPDATA%\Google\Chrome\User Data\Default` | ### Manual Configuration If automatic detection fails, manually configure paths in `server/main.py`: ```python FIREFOX_PROFILE_DIR = "/path/to/your/firefox/profile" CHROME_PROFILE_DIR = "/path/to/your/chrome/profile" ``` ### Development Mode ```bash uv run mcp dev server/main.py ``` **Pro tip**: Open the version of the local URL with the token pre-filled. Then hit "Connect" ### Use with Claude Desktop ```bash uv run mcp install server/main.py --name "Browser History MCP" ``` ## 📚 API Reference ### Core Tools | Tool | Description | Use Case | |------|-------------|----------| | `health_check` | Simple health check to test if the MCP server is working | Initial testing | | `check_browser_status` | Step 1: Check which browsers are available and which are locked | Initial setup and troubleshooting | | `get_browser_history` | Step 2: Get raw browser history data without analysis (fastest) | Quick data retrieval | | `analyze_browser_history` | Step 3: Main analysis tool with options for quick_summary, basic, or comprehensive analysis | Full productivity analysis | | `search_browser_history` | Search browser history for specific queries | Targeted research | | `suggest_categories` | Get uncategorized URLs for custom categorization | Data organization | | `diagnose_safari_support` | Safari support and accessibility diagnostics | Safari-specific issues | ### Analysis Prompts | Prompt | Purpose | Output | |--------|---------|--------| | `productivity_analysis` | Comprehensive productivity assessment | Productivity metrics and recommendations | | `learning_analysis` | Deep learning pattern analysis | Learning insights and progress tracking | | `research_topic_extraction` | Research topic extraction and summarization | Research themes and focus areas | | `generate_insights_report` | Create personalized browsing insights | Comprehensive activity and behavior report | | `compare_time_periods` | Compare browsing habits across time | Trend analysis and habit transformation metrics | | `export_visualization` | Generate data visualizations | Interactive charts and visual analytics | ## 🌐 Browser Support | Browser | Status | Requirements | |---------|--------|--------------| | **Firefox** | ✅ Full Support | Browser must be closed | | **Chrome** | ✅ Full Support | Browser must be closed | | **Safari** | 🔄 Limited Support | Mostly older versions of Safari | **Important**: Browsers must be closed to access their history databases due to file locking mechanisms. ## Troubleshooting ### MCP Config ``` { "mcpServers": { "Browser History MCP": { "command": "/usr/local/bin/uv", "args": [ "run", "--with", "mcp[cli]", "mcp", "run", "[wherever-you-saved-the-repo]/browser-mcp-server/server/main.py" ] } } } ``` ## 🔒 Privacy & Security ### Data Handling - **Local Processing**: All data processing occurs locally on your machine - **No Data Transmission**: No browser history data is sent to external servers (aside from whatever Claude desktop is doing) - **Direct Database Access**: Reads directly from browser SQLite databases - **Temporary Caching**: Optional local caching for performance ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.