# 🦁 Brave Browser MCP Server

A powerful **Model Context Protocol (MCP)** server that gives AI agents full control over your **Brave Browser**. Unlike standard automation, this server is optimized for **local LLMs** (like Qwen3.5 27B) to ensure low latency and high reliability.

---

## ⚡ Quick Setup

### 1. Install dependencies
```bash
pip install mcp[cli] playwright
playwright install chromium
```
> **Note:** Even though we use Brave, Playwright needs its driver components to control it.

### 2. Add to Claude Desktop (or your MCP Host)
Edit your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "brave-browser": {
      "command": "python",
      "args": ["C:/PATH/TO/MCP-Brave-Browser/server.py"]
    }
  }
}
```

---

## 🔧 Optimized Tools (27)

### Speed & Discovery (VITAL for Local Models)
| Tool | Description |
|------|-------------|
| `page_summary` | **Instant Orientation.** Returns Title, H1s, and Meta info. Use this first to save context. |
| `find_elements` | **Targeted Search.** Finds specific items by text/URL. Faster than reading a whole page. |
| `snapshot` | **Accessibility Tree.** Returns elements with `ref=N` IDs. |

### Navigation
| Tool | Description |
|------|-------------|
| `navigate` | Opens a URL. |
| `get_page_info` | Returns current URL and page title. |
| `tabs` | List, open, close, or switch tabs. |

### Page Interaction
| Tool | Description |
|------|-------------|
| `click` / `hover` | Interact via CSS selector or `ref=N` from snapshot. |
| `type_text` | Real-time character typing. |
| `fill_input` | Instant form filling. |
| `take_screenshot` | Visual verification (Timestamped in `/screenshots`). |

---

## 🚀 Performance Tips (Context & Compute)

If you are using a **local 4B-9B model**, full page snapshots can be slow. Use these strategies to make it lightning fast:

1.  **Filter Noise**: Use `snapshot(interactive_only=True)`. This strips out `div`, `section`, and `nav` containers, returning only the interactive elements. It usually reduces context size by **70%**.
2.  **Scope your Search**: Use `snapshot(selector="#main-content")` to only see a specific part of the page.
3.  **Use Summaries First**: Instead of taking a snapshot immediately, call `page_summary()` to understand where you are.
4.  **Targeted Discovery**: Use `find_elements(query="Login")` if you just need to find one specific button.

---

## ⚙️ Configuration

| Setting | Default | Override |
|---------|---------|----------|
| Brave path | `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe` | Set `BRAVE_EXECUTABLE_PATH` env var |
| Profile Path | `./brave_mcp_profile` | Managed automatically (Persistent sessions) |

---

## 📦 Dependencies
- `mcp[cli]` — FastMCP framework
- `playwright` — High-speed browser automation engine

---

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.