# blackmount-mcp

[![PyPI](https://img.shields.io/pypi/v/blackmount-mcp)](https://pypi.org/project/blackmount-mcp/)
[![Downloads](https://img.shields.io/pypi/dm/blackmount-mcp)](https://pypistats.org/packages/blackmount-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=blackmount&config=eyJjb21tYW5kIjoiYmxhY2ttb3VudC1tY3AifQ==)

Your AI assistant is blind to your browsing life. Claude doesn't know what you researched yesterday, what tabs you have open, or what articles you bookmarked. **blackmount-mcp fixes that.**

Connect your local browser history, bookmarks, open tabs, and downloads directly to Claude, Cursor, or any MCP client. All data stays on your machine — nothing leaves your disk.

## Quick Start

```bash
pip install blackmount-mcp
```

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "blackmount": {
      "command": "blackmount-mcp"
    }
  }
}
```

Restart Claude Desktop. Done.

## What can you ask?

Once connected, try these in Claude:

- *"What was that article about React Server Components I read last Tuesday?"*
- *"How much time did I spend on Reddit vs GitHub this week?"*
- *"Find all the ML papers I bookmarked"*
- *"What tabs do I have open right now?"*
- *"Summarize what I researched yesterday"*
- *"Find that pricing page I visited for Vercel — I need to compare it"*
- *"What did I download from arxiv in the last month?"*
- *"Show me everything I've browsed about LLM fine-tuning"*
- *"When do I browse the most — mornings or evenings?"*
- *"Find that GitHub PR tab I have open somewhere"*

## Tool Catalog

### Browser

| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `search_history` | Search browsing history by keyword | *"Find that React article I read last week"* |
| `list_history` | Recent browsing history | *"What sites did I visit today?"* |
| `find_page` | Natural language page search | *"That TypeScript tutorial I read"* |
| `search_bookmarks` | Search bookmarks by title/URL | *"Find my saved Python tutorials"* |
| `list_bookmarks` | Browse bookmark folders | *"What's in my Work bookmarks folder?"* |
| `get_open_tabs` | List currently open tabs | *"What tabs do I have open?"* |
| `find_tab` | Find a specific open tab | *"Find that GitHub PR tab"* |
| `list_downloads` | Recent file downloads | *"What did I download this week?"* |

### Analytics

| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `browsing_summary` | Daily browsing summary | *"Summarize my browsing today"* |
| `daily_digest` | Daily digest of local browsing | *"What did I do online yesterday?"* |
| `productivity_report` | Weekly productivity summary | *"How productive was I this week?"* |
| `domain_time` | Time spent per domain | *"Where do I spend my time online?"* |
| `distraction_score` | Focus vs distraction ratio | *"Am I getting distracted?"* |
| `most_visited` | Top domains by visits | *"My most visited sites this month"* |
| `research_topics` | Clustered research topics | *"What have I been researching?"* |
| `browsing_patterns` | Peak hours, trends | *"When do I browse the most?"* |

## Claude Desktop Config

```json
{
  "mcpServers": {
    "blackmount": {
      "command": "blackmount-mcp"
    }
  }
}
```

Config file locations:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

## Cursor

One-click install via the badge at the top of this README, or add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "blackmount": {
      "command": "blackmount-mcp"
    }
  }
}
```

## Supported Browsers

| Tool family | Browsers |
|---|---|
| History | Chrome, Firefox, Safari, Edge, Brave, Opera, Vivaldi |
| Bookmarks | Chrome, Firefox, Safari |
| Downloads | Chrome, Firefox, Safari |
| Open tabs | Chrome, Safari (macOS via AppleScript; Chrome session-file fallback elsewhere) |

## Privacy

- All data is read locally from your machine
- No network requests, no telemetry, no cloud
- Open source (MIT) — audit the code yourself

## Companion Apps

- **[app.blackmount.ai](https://app.blackmount.ai)** — web dashboard for visual browsing analytics
- **Blackmount for iOS** — mobile access to your work context

## Development

```bash
git clone https://github.com/BlackMount-ai/blackmount-mcp.git
cd blackmount-mcp
pip install -e .
pytest tests/ -v
blackmount-mcp
```

## Contributing

Pull requests welcome. Open an issue to discuss larger changes.

## Links

- [blackmount.ai](https://blackmount.ai) — Home
- [app.blackmount.ai](https://app.blackmount.ai) — Web dashboard
- [PyPI](https://pypi.org/project/blackmount-mcp/) — Package
- [GitHub](https://github.com/BlackMount-ai/blackmount-mcp) — Source

## License

MIT