Browser History 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, this tool can be added to Claude desktop in a few minutes using the Quick Start guide.

📋 Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• API Reference
• Browser Support
• Troubleshooting
• Privacy & Security
• 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:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync

2. Test locally:

   uv run mcp dev server/main.py

3. Install for Claude Desktop (you will need to restart Claude Desktop afterwards):

   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 (recommended) or pip

Using uv (Recommended)

# 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

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:

FIREFOX_PROFILE_DIR = "/path/to/your/firefox/profile"
CHROME_PROFILE_DIR = "/path/to/your/chrome/profile"

Development Mode

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

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 file for details.