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

Install uv for dependency management:

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

Test locally:
```
uv run mcp dev server/main.py
```
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.

Browser History Analysis MCP

README Documentation