Brave Search AI MCP

A local, stdio-based Model Context Protocol server that lets MCP-compatible AI clients search the web with Brave Search AI. It returns the generated answer, source citations, and suggested follow-up questions.

This project is independent and is not affiliated with or endorsed by Brave Software.

What it does

The server runs a headless Chromium browser locally with Playwright, opens a Brave Search results page, and extracts the AI answer and citations. It does not use a Brave Search API key. Search terms are sent to Brave Search, and the scraping implementation may need updates if Brave changes its website. Use it in accordance with Brave's terms and applicable rate limits.

Related MCP server: Brave Search MCP Server

Requirements

• Python 3.12 or newer

• uv

• Chromium dependencies supported by Playwright

No Brave account or API key is required by this server.

Install

Clone the repository and run the setup script:

git clone https://github.com/VexCoreAI/brave-search-ai-mcp.git
cd brave-search-ai-mcp
./scripts/setup.sh

The script creates a project virtual environment, installs locked dependencies, and downloads Playwright Chromium. On Linux, Playwright may require system packages; see its browser installation guide.

To start the server manually:

./run.sh

The process speaks MCP over standard input and output. Do not start it in a terminal and expect human-readable output. Protocol diagnostics are written to standard error.

If Playwright Chromium cannot start and Chrome is installed on the machine, set BRAVE_BROWSER_CHANNEL=chrome in the MCP server's environment. The scraper falls back to bundled Chromium if that channel cannot launch.

MCP tool

brave_search

Searches the web and returns the Brave Search AI response and source citations.

Successful calls return JSON with this shape:

{
  "query": "What is the Model Context Protocol?",
  "has_ai_response": true,
  "answer": "...",
  "citations": [
    { "url": "https://example.com/", "title": "Example", "snippet": "..." }
  ],
  "followups": ["..."],
  "conversation_id": "...",
  "strategy": "SSE Network Interception",
  "error": null
}

If the search cannot be completed, the result includes a non-empty error. has_ai_response can be false when Brave returns search results without an AI answer. Citations and follow-up questions may be empty.

Connect an AI client

This server uses the standard local stdio transport, so no hosted endpoint, account, or API key is needed. First complete the installation above. Replace /ABSOLUTE/PATH below with the actual path to the cloned repository. Some desktop clients do not inherit your shell PATH, so use the full path to run.sh and restart the client after changing its MCP configuration.

Claude Desktop

Add this entry to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "brave-search-ai": {
      "command": "/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"
    }
  }
}

See Claude Desktop local MCP setup.

Claude Code

claude mcp add --scope user --transport stdio brave-search-ai -- /ABSOLUTE/PATH/brave-search-ai-mcp/run.sh

Check the connection with claude mcp list. See the Claude Code MCP guide.

OpenCode

Add a local server to the mcp.servers section of opencode.json:

{
  "mcp": {
    "servers": {
      "brave-search-ai": {
        "type": "local",
        "command": ["/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"],
        "enabled": true
      }
    }
  }
}

See the OpenCode MCP server guide.

Cursor

Add the server to .cursor/mcp.json in a project, or to your user-level Cursor MCP configuration:

{
  "mcpServers": {
    "brave-search-ai": {
      "command": "/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"
    }
  }
}

See Cursor MCP configuration.

Visual Studio Code with GitHub Copilot

Add this server to .vscode/mcp.json:

{
  "servers": {
    "brave-search-ai": {
      "type": "stdio",
      "command": "/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"
    }
  }
}

See VS Code MCP server configuration.

Windsurf

Add this entry to Windsurf's mcp_config.json:

{
  "mcpServers": {
    "brave-search-ai": {
      "command": "/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"
    }
  }
}

See the Windsurf MCP guide.

Gemini CLI

Add this entry to ~/.gemini/settings.json:

{
  "mcpServers": {
    "brave-search-ai": {
      "command": "/ABSOLUTE/PATH/brave-search-ai-mcp/run.sh"
    }
  }
}

See the Gemini CLI MCP guide.

Other MCP clients

Configure a local MCP server using stdio and set its command to the absolute path of run.sh. If a client requires separate command and argument fields, use the script path as the command and leave the argument list empty. The MCP transport is client-neutral; the configuration file format and MCP support vary by client.

Development

uv sync --locked --all-groups
uv run playwright install chromium
uv run ruff check .
uv run ruff format --check .
uv run pytest

Tests use mocked search results and parser fixtures. They do not launch a real browser or send queries to Brave.

Attribution and licensing

The scraper is derived from ijuttt/scrape-brave-ai and is included with permission. See NOTICE.md for attribution. This repository is distributed under the MIT License in LICENSE, with permission covering the upstream-derived code. The upstream repository itself does not provide a license file.

Limitations

• Brave's website and private response formats can change without notice.

• Brave may rate-limit or block automated browser traffic.

• The server returns Brave's AI answer when available; it is not a general purpose browser automation server or a guaranteed search API.

• This implementation uses stdio only. It does not expose a remote HTTP server.