> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshbrow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Give AI agents stealth browser capabilities via the Model Context Protocol

# MCP Server

The `meshbrow-mcp` server exposes Meshbrow's stealth browser capabilities as MCP tools. Compatible with Claude Desktop, VS Code Copilot, Cursor, and any MCP-compatible client.

## Installation

<Tabs>
  <Tab title="Homebrew (macOS/Linux)">
    ```bash theme={null}
    brew tap meshbrow-dev/tap
    brew install meshbrow-mcp
    ```
  </Tab>

  <Tab title="Go Install">
    ```bash theme={null}
    go install github.com/meshbrow-dev/meshbrow-mcp@latest
    ```
  </Tab>

  <Tab title="Binary">
    ```bash theme={null}
    curl -fsSL https://github.com/meshbrow-dev/meshbrow-mcp/releases/latest/download/meshbrow-mcp-linux-amd64 \
      -o /usr/local/bin/meshbrow-mcp
    chmod +x /usr/local/bin/meshbrow-mcp
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker pull ghcr.io/meshbrow-dev/meshbrow-mcp:latest
    ```
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
meshbrow-mcp --version
# meshbrow-mcp v0.1.0
```

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "meshbrow": {
      "command": "meshbrow-mcp",
      "args": ["--mode", "stdio"],
      "env": {
        "MESHBROW_API_KEY": "mb_live_your_key_here"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project:

```json theme={null}
{
  "servers": {
    "meshbrow": {
      "command": "meshbrow-mcp",
      "args": ["--mode", "stdio"],
      "env": {
        "MESHBROW_API_KEY": "mb_live_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "meshbrow": {
      "command": "meshbrow-mcp",
      "args": ["--mode", "stdio"],
      "env": {
        "MESHBROW_API_KEY": "mb_live_your_key_here"
      }
    }
  }
}
```

### Standalone (WebSocket)

Run the MCP server over WebSocket for remote/shared access:

```bash theme={null}
meshbrow-mcp --mode ws --port 9090 --api-key mb_live_...
```

## CLI Flags

| Flag          | Env Variable         | Default                    | Description                |
| ------------- | -------------------- | -------------------------- | -------------------------- |
| `--mode`      | `MESHBROW_MCP_MODE`  | `stdio`                    | Transport: `stdio` or `ws` |
| `--port`      | `MESHBROW_MCP_PORT`  | `9090`                     | WebSocket listen port      |
| `--api-url`   | `MESHBROW_API_URL`   | `https://api.meshbrow.dev` | API endpoint               |
| `--api-key`   | `MESHBROW_API_KEY`   | (required)                 | Your API key               |
| `--log-level` | `MESHBROW_LOG_LEVEL` | `info`                     | Log level                  |

## Available Tools

### Session Management

| Tool              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `session_create`  | Launch a stealth browser session with proxy and fingerprint |
| `session_list`    | List all active sessions                                    |
| `session_get`     | Get session details and CDP endpoint                        |
| `session_destroy` | Destroy a session (optionally save profile)                 |

### Browser Actions

| Tool                 | Description                      |
| -------------------- | -------------------------------- |
| `browser_navigate`   | Navigate to a URL                |
| `browser_screenshot` | Take a screenshot (base64 PNG)   |
| `browser_click`      | Click an element by CSS selector |
| `browser_type`       | Type text into an input field    |
| `browser_extract`    | Extract text/data from the page  |
| `browser_execute`    | Execute arbitrary JavaScript     |
| `browser_wait`       | Wait for an element to appear    |
| `browser_scroll`     | Scroll the page                  |

### Profiles

| Tool             | Description                         |
| ---------------- | ----------------------------------- |
| `profile_create` | Create a persistent browser profile |
| `profile_list`   | List saved profiles                 |
| `profile_get`    | Get profile details                 |
| `profile_delete` | Delete a profile                    |

### Fleet

| Tool            | Description                          |
| --------------- | ------------------------------------ |
| `fleet_create`  | Launch multiple sessions in parallel |
| `fleet_status`  | Check fleet session statuses         |
| `fleet_destroy` | Destroy all fleet sessions           |

## Example: AI Agent Web Research

```
User: "Find the current price of Bitcoin on CoinGecko"

Agent calls: session_create({ stealth: "max", proxy_country: "US" })
→ Returns: { id: "sess_abc123", cdp_endpoint: "wss://..." }

Agent calls: browser_navigate({ session_id: "sess_abc123", url: "https://coingecko.com/en/coins/bitcoin" })
→ Returns: { status: "loaded" }

Agent calls: browser_extract({ session_id: "sess_abc123", selector: "[data-target='price.price']" })
→ Returns: { result: "$67,432.12" }

Agent calls: session_destroy({ session_id: "sess_abc123" })
→ Returns: { status: "destroyed" }

Agent responds: "The current Bitcoin price on CoinGecko is $67,432.12"
```

## Security

The MCP server enforces:

* **API key required** — all tool calls require a valid `MESHBROW_API_KEY`
* **Session isolation** — each session runs in its own network namespace
* **No credential leakage** — proxy credentials and fingerprint internals are never exposed in tool responses
* **Structured logging** — all operations are logged to stderr (never stdout, which is reserved for MCP protocol)

## Best Practices

<AccordionGroup>
  <Accordion title="Reuse sessions across related tasks">
    Don't create a new session for every page. Navigate within the same session when visiting related pages — it's faster and uses fewer resources.
  </Accordion>

  <Accordion title="Use profiles for authenticated workflows">
    Store login cookies in profiles so agents don't need to re-authenticate each time.
  </Accordion>

  <Accordion title="Always destroy sessions">
    Include cleanup in your agent's error handling. Leaked sessions cost money and resources.
  </Accordion>

  <Accordion title="Prefer extract over screenshots">
    Text extraction is faster and uses fewer tokens than screenshot-based approaches.
  </Accordion>
</AccordionGroup>