Brave Search MCP Server

A stateless Model Context Protocol (MCP) server for Brave Search API integration with Bearer token authentication.

Features

Stateless Architecture: Complete request isolation with no session management
Bearer Token Authentication: Standard Authorization header support
Web Search: General queries, news, articles, with pagination and freshness controls
Local Search: Find businesses, restaurants, and services with detailed information
Token Validation: Built-in API key validation

Quick Start

Start the Server

# Install dependencies
npm install

# Build the project
npm run build

# Start the stateless server
npm start

The server will start on port 30000 by default. You can also set a custom port:

PORT=8080 npm start

Authentication

The server uses standard Bearer token authentication. Include your Brave Search API key in the Authorization header:

Authorization: Bearer YOUR_BRAVE_API_KEY_HERE

Get your API key from the Brave Search API Dashboard.

Tools and CURL Examples

1. List Available Tools

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_BRAVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test",
    "method": "tools/list",
    "params": {}
  }'

2. Validate Token

Validate your Brave Search API key:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "validate",
    "method": "tools/call",
    "params": {
      "name": "validate_token",
      "arguments": {
        "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
      }
    }
  }'

3. Web Search

Perform a general web search:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_BRAVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "web-search",
    "method": "tools/call",
    "params": {
      "name": "brave_web_search",
      "arguments": {
        "query": "artificial intelligence news",
        "count": 10,
        "offset": 0
      }
    }
  }'

4. Web Search with Pagination

Search with pagination (get next page):

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_BRAVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "web-search-page2",
    "method": "tools/call",
    "params": {
      "name": "brave_web_search",
      "arguments": {
        "query": "machine learning tutorials",
        "count": 20,
        "offset": 1
      }
    }
  }'

5. Local Business Search

Search for local businesses and services:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_BRAVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "local-search",
    "method": "tools/call",
    "params": {
      "name": "brave_local_search",
      "arguments": {
        "query": "pizza restaurants near Central Park NYC",
        "count": 5
      }
    }
  }'

6. Local Search with More Results

Get more local search results:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_BRAVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "local-search-more",
    "method": "tools/call",
    "params": {
      "name": "brave_local_search",
      "arguments": {
        "query": "coffee shops San Francisco",
        "count": 15
      }
    }
  }'

Error Handling Examples

No Authentication Token

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "no-auth",
    "method": "tools/call",
    "params": {
      "name": "brave_web_search",
      "arguments": {"query": "test"}
    }
  }'

Invalid Token Format

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Invalid token_format" \
  -d '{
    "jsonrpc": "2.0",
    "id": "invalid-format",
    "method": "tools/call",
    "params": {
      "name": "brave_web_search",
      "arguments": {"query": "test"}
    }
  }'

Invalid API Key

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer invalid_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "invalid-key",
    "method": "tools/call",
    "params": {
      "name": "brave_web_search",
      "arguments": {"query": "test"}
    }
  }'

Tool Parameters

brave_web_search

query (required): Search query (max 400 chars, 50 words)
count (optional): Number of results (1-20, default 10)
offset (optional): Pagination offset (max 9, default 0)

brave_local_search

query (required): Local search query (e.g., 'pizza near Central Park')
count (optional): Number of results (1-20, default 5)

validate_token

BRAVE_API_KEY (required): Brave Search API key to validate

Notes

The server runs in stateless mode only
Each request gets a fresh server instance for complete isolation
No session management or token caching
Rate limiting is applied per request
Local search automatically falls back to web search if no local results are found
Server listens on port 30000 by default

Package detail

@gongrzhe/server-brave-search-mcp

readme