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