graph TD
    A[Your Application] -->|imports| B[BraveClient]
    C[MCP Client<br/>Claude Desktop / Claude Code / other] -->|stdio| D[Brave API MCP Server]
    G[OpenAI-compatible Client<br/>or remote agent] -->|HTTP / SSE| D
    D -->|ask / search / suggest| B
    B --> E[HTTPClient<br/>curl_cffi]
    E --> F[Brave Search / Brave AI]

    style B fill:#2b2b2b,stroke:#888,color:#fff
    style D fill:#2b2b2b,stroke:#888,color:#fff
    style F fill:#1a1a1a,stroke:#888,color:#fff

uv pip install brave-api-python

git clone https://github.com/iqbalmh18/brave-api
cd brave-api
uv pip install -e ".[dev]"

uv pip install "brave-api-python[mcp]"

import asyncio
from brave_api import BraveClient

async def main():
    async with BraveClient() as client:
        # AI answer
        result = await client.ask("what is quantum computing?")
        print(result.text)

        # Web search
        search = await client.search("python asyncio tutorial")
        for item in search.web:
            print(item.title, item.url)

asyncio.run(main())

async with BraveClient() as client:
    result = await client.ask("mount bromo indonesia")

print(result.text)           # AI answer text (markdown)

if result.infobox:
    print(result.infobox.title)      # "Mount Bromo"
    print(result.infobox.subtitle)   # "Active volcano in East Java"
    print(result.infobox.url)        # Wikipedia URL
    print(result.infobox.image_url)  # entity image

for img in result.images:
    print(img.url, img.thumbnail)

for vid in result.videos:
    print(vid.title, vid.url)

for web in result.web_results:
    print(web.title, web.url)

for q in result.followups:
    print(q)

from pathlib import Path

result = await client.ask("what is in this image?", image=Path("photo.jpg"))

async for event in client.ask_stream("what is Space X?"):
    if event.type is StreamEventType.TEXT_DELTA:
        print(event.delta, end="", flush=True)
    elif event.type is StreamEventType.TEXT_STOP:
        print()
    elif event.type is StreamEventType.FOLLOWUPS:
        for q in event.payload.get("followups", []):
            print(f"-> {q}")

async with BraveClient() as client:
    result = await client.search("python asyncio tutorial")

print(result.query)          # original query
print(len(result.web))       # number of web results
print(len(result.news))      # number of news results

for item in result.web:
    print(item.title)
    print(item.url)
    print(item.description)
    print(item.age)          # "2 days ago", etc.

for item in result.news:
    print(item.title, item.source, item.age)

# All unique URLs in a flat list
for url in result.urls:
    print(url)

# Page 1 (default)
page1 = await client.search("rust programming", offset=0)

# Page 2
page2 = await client.search("rust programming", offset=1)

result = await client.search("pyton tutorial", spellcheck=False)

suggestions = await client.suggest("elon")
for s in suggestions:
    print(s.text, s.entity_type, s.is_entity)
    if s.thumbnail:
        print(s.thumbnail)

from brave_api import BraveClient, ClientConfig

config = ClientConfig(
    # Language and region
    language="id",                   # Response language: "id", "en", etc.
    ui_lang="id-id",                 # UI language: "id-id", "en-us", etc.
    country="id",                    # ISO 3166-1 country code
    geoloc="-6.200x106.816",         # lat x lng (Jakarta)

    # Search
    safesearch="moderate",           # "off", "moderate", or "strict"
    units_of_measurement="metric",   # "metric" or "imperial"

    # Mode
    enable_research=False,           # True = deep research mode

    # HTTP
    request_timeout_seconds=60.0,
    max_retries=3,
    retry_backoff_seconds=1.5,

    # Optional proxy pool
    proxy_list=[
        "http://user:password@proxy-1.example:8080",
        "socks5://proxy-2.example:1080",
    ],

    # Browser fingerprinting
    impersonate="chrome136",
    extra_headers={"X-Custom": "value"},
)

async with BraveClient(config) as client:
    ...

from brave_api import BraveClient, ClientConfig

config = ClientConfig(
    proxy_list=[
        "http://user:password@proxy-1.example:8080",
        "http://proxy-2.example:8080",
        "socks5://proxy-3.example:1080",
    ],
)

async with BraveClient(config) as client:
    result = await client.search("python asyncio tutorial")

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)

async with BraveClient() as client:
    # New conversation
    conv = await client.conversation("explain how DNS works")
    result = await conv.collect()

    # Continue the same conversation
    conv2 = await client.conversation(
        "what is DNSSEC?",
        conversation_id=conv.id,
        symmetric_key=conv.symmetric_key,
    )
    result2 = await conv2.collect()

async for event in conv.stream_events():
    if event.type is StreamEventType.TEXT_DELTA:
        print(event.delta, end="", flush=True)
    elif event.type is StreamEventType.TEXT_STOP:
        print()
    elif event.type is StreamEventType.ERROR:
        print(f"Error: {event.error_message}")

TEXT_DELTA / TEXT_STOP                    response text tokens
THINKING_DELTA / THINKING_STOP            chain-of-thought reasoning
TOOL_USE                                  server requests a tool call
AUGMENT_WITH_TOOL_USE                     run_tool result (web results, images, etc.)
AUGMENT_WITH_WEB / NEWS / IMAGES / VIDEOS enrichment data
AUGMENT_WITH_INFOBOX                      entity knowledge card
FOLLOWUPS                                 suggested follow-up questions
ERROR                                     server error event
CHALLENGE                                 CAPTCHA required

sequenceDiagram
    participant App
    participant Client as BraveClient
    participant Brave as Brave AI

    App->>Client: ask(query)
    Client->>Brave: POST /api/tap/v1/new
    Brave-->>Client: SSE stream

    loop until stream ends
        Brave-->>Client: TEXT_DELTA / THINKING_DELTA
        Brave-->>Client: AUGMENT_WITH_WEB / IMAGES / INFOBOX
    end

    Brave-->>Client: FOLLOWUPS
    Client-->>App: StreamResult

result = await conv.collect()

result.text            # str - full AI answer (markdown)
result.thinking         # str - chain-of-thought reasoning (if any)
result.urls             # list[str] - unique URLs found
result.images           # list[ImageResult]
result.videos           # list[VideoResult]
result.web_results      # list[WebResult]
result.infobox          # Infobox | None
result.followups        # list[str]
result.citations        # list[dict] - raw tool result payloads
result.inline_entities  # list[dict]
result.raw_events       # list[StreamEvent] - every event for debugging
result.state            # StreamState enum
result.is_complete      # bool
result.has_images       # bool
result.has_videos       # bool
result.has_infobox      # bool
result.has_tool_calls   # bool

BraveAPIError
├── TransportError          network error, timeout, connection reset
├── HTTPStatusError         non-2xx HTTP response (.status_code, .response_text)
├── TokenExtractionError    could not parse auth token from server HTML
├── ConversationError       /api/tap/v1/new did not return a conversation id
├── StreamAbortedError      server sent an error event mid-stream
├── ChallengeRequiredError  server sent a CAPTCHA challenge
└── InvalidResponseError    response was not valid JSON or unexpected shape

from brave_api.exceptions import (
    BraveAPIError, ChallengeRequiredError, HTTPStatusError,
    StreamAbortedError, TransportError,
)

try:
    async with BraveClient() as client:
        result = await client.ask("what is rust?")
except ChallengeRequiredError:
    print("CAPTCHA required")
except HTTPStatusError as e:
    print(f"HTTP {e.status_code}: {e.response_text[:200]}")
except TransportError as e:
    print(f"Network error: {e}")
except StreamAbortedError as e:
    print(f"Stream aborted: {e}")
except BraveAPIError as e:
    print(f"Error: {e}")

python -m brave_api.mcp.server
# or via the CLI entry-point
brave-api-mcp

brave-api-mcp --http
# bind to a specific host/port
brave-api-mcp --http --host 0.0.0.0 --port 8000

usage: brave-api-mcp [-h] [--http] [--host HOST] [--port PORT]
                     [--log-level {debug,info,warning,error,critical}]

options:
  --http              Run with HTTP/SSE transport instead of stdio.
  --host HOST         Host address to bind to (HTTP transport only). [default: 127.0.0.1]
  --port PORT         Port to bind to (HTTP transport only). [default: 8000]
  --log-level LEVEL   Logging level. [default: warning]

{
  "mcpServers": {
    "brave-api": {
      "command": "python",
      "args": ["-m", "brave_api.mcp.server"],
      "env": {
        "BRAVE_COUNTRY": "id",
        "BRAVE_LANGUAGE": "id",
        "BRAVE_SAFESEARCH": "moderate"
      }
    }
  }
}

claude mcp add brave-api python -- -m brave_api.mcp.server

brave-api-mcp --http --host 0.0.0.0 --port 8000