brave-api-python 1.1.0

An async Python client for Brave Search, providing streaming AI answers and structured web search in a single, typed interface - with a built-in Model Context Protocol (MCP) server.

Features

• Async Brave Ask client with blocking and streaming responses
• Multi-turn conversations and multimodal image input
• Structured search for web, images, news, videos, and Brave Goggles
• Pagination, autocomplete suggestions, and typed Pydantic models
• Configurable language, region, safe search, timeout, retries, and proxies
• FastMCP server with stdio and HTTP transports

Documentation

The complete documentation is available at brave-api-python.readthedocs.io.

It includes detailed guides, configuration, MCP setup, examples, error handling, and the generated API reference.

Installation

Requires Python 3.11+.

uv add brave-api-python

For MCP support:

uv add "brave-api-python[mcp]"

With pip:

pip install brave-api-python

From source:

git clone https://github.com/iqbalmh18/brave-api.git
cd brave-api
uv sync --group dev

Quick start

Ask

import asyncio

from brave_api import BraveClient


async def main() -> None:
    async with BraveClient() as client:
        result = await client.ask("What is quantum computing?")

    print(result.text)
    print(f"Sources: {len(result.urls)}")


asyncio.run(main())

Search

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

for item in result.web[:3]:
    print(item.title, item.url)

All public methods are asynchronous and should normally be used inside async with BraveClient().

Search verticals

Every search method returns the same SearchResult response envelope:

async with BraveClient() as client:
    web = await client.search("Python asyncio")
    images = await client.search_images("Python logo")
    news = await client.search_news("Python release")
    videos = await client.search_videos("Python tutorial")
    goggles = await client.search_goggles("privacy search")

print(web.web)
print(images.images)
print(news.news)
print(videos.videos)
print(goggles.web)

Pagination uses Brave's page-based offset value, where 0 is the first page:

async with BraveClient() as client:
    first_page = await client.search_news("Python release", offset=0)
    second_page = await client.search_news("Python release", offset=1)

Use spellcheck=False for exact keyword matching. Use client.suggest() for autocomplete suggestions.

Streaming

from brave_api import BraveClient, StreamEventType

async with BraveClient() as client:
    async for event in client.ask_stream("Explain WebAssembly"):
        if event.type is StreamEventType.TEXT_DELTA:
            print(event.delta, end="", flush=True)

Configuration

from brave_api import BraveClient, ClientConfig

config = ClientConfig(
    language="id",
    ui_lang="id-id",
    country="id",
    safesearch="moderate",
    timeout=60.0,
    max_retries=3,
    proxies=["http://user:password@proxy.example:8080"],
)

async with BraveClient(config) as client:
    result = await client.search("berita teknologi")

See the configuration guide for all supported options.

MCP server

Install the optional MCP dependency:

uv add "brave-api-python[mcp]"

Run locally over stdio:

brave-api-mcp

Or run an HTTP server:

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

Available search tools include search, search_images, search_news, search_videos, search_goggles, and suggest, in addition to ask.

Examples

Runnable examples are available in examples/:

• search_verticals.py — all search verticals and pagination
• search_suggest.py — web search and autocomplete
• streaming.py — streaming events
• multimodal.py — image input
• configuration.py — configuration and proxies

Run one with:

uv run python examples/search_verticals.py

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright

For API details, error handling, conversations, and complete MCP configuration, see the full documentation.

Star History

License

MIT. See LICENSE.