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:

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

Analysis Prompts

🌐 Browser Support

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.