Brave Search MCP Server

Exposes Brave Search API as an MCP tool that LLM clients invoke through standardized JSON-RPC protocol. The server translates natural language search queries into Brave API calls, handles authentication via API key, and returns structured results (title, description, URL) formatted for LLM consumption. Uses MCP's tool registration pattern to declare search parameters as a schema, enabling type-safe invocation from any MCP-compatible client.

Extends web search capability to perform location-aware business searches via Brave's local search API. Accepts geographic parameters (latitude/longitude or location name) and business query terms, returns structured business results with addresses, phone numbers, and ratings. Implements location-based filtering at the API layer before returning results to the LLM, reducing irrelevant results and improving context relevance for location-dependent queries.

Implements MCP's tool registration pattern to declare search capabilities as discoverable, schema-validated tools. The server defines tool metadata (name, description, input schema with JSON Schema) and registers tools with the MCP server runtime. Clients query the server's tool list via MCP's tools/list endpoint, receive schema definitions, and validate user inputs against schemas before invocation. This enables type-safe, self-documenting tool discovery without hardcoded client knowledge.

Implements JSON-RPC 2.0 protocol layer for all search requests and responses. The server exposes tools/call endpoint that accepts JSON-RPC requests with tool name and parameters, executes the corresponding search operation, and returns results wrapped in JSON-RPC response format. Handles request/response correlation via JSON-RPC message IDs, enabling asynchronous and batched tool invocations. Supports both stdio and HTTP transport mechanisms for client-server communication.

Transforms raw Brave Search API responses into LLM-optimized structured format. Extracts and normalizes key fields (title, description, URL) from API responses, removes HTML/formatting noise, truncates long descriptions to fit context windows, and orders results by relevance. Returns results as clean JSON arrays that LLMs can easily parse and reason about, with consistent field naming and types across web and local search results.

Manages Brave Search API authentication by accepting API key via environment variable (BRAVE_SEARCH_API_KEY) or configuration file. The server validates the API key on startup and includes it in all outbound Brave API requests via Authorization header. Implements credential isolation so API keys are never exposed in logs, error messages, or client responses. Supports credential rotation by reloading environment variables without server restart.

Implements error handling for Brave API failures, network timeouts, and invalid search parameters. Maps Brave API error responses (rate limit, invalid query, auth failure) to MCP error format with descriptive messages. Implements exponential backoff retry logic for transient failures (network timeouts, 5xx errors) with configurable retry count. Returns structured error responses to clients that distinguish between client errors (invalid parameters) and server errors (API unavailable).

Validates search query parameters against the declared JSON Schema before invoking Brave API. Checks query length (typically 1-2000 characters), parameter types (string vs number), and optional parameters (count, offset, safesearch level). Sanitizes queries to remove potentially problematic characters or encoding issues. Returns validation errors to clients before making API calls, preventing malformed requests and reducing unnecessary API quota usage.

Handles concurrent search requests from multiple MCP clients through asynchronous request processing. Each search request is processed independently without blocking other clients, using Node.js async/await patterns or Python asyncio. Maintains separate API rate limits and quota tracking per client (if configured), preventing one client's heavy usage from starving others. Implements request queuing if Brave API rate limits are approached, distributing quota fairly across concurrent clients.

Serves as official MCP reference implementation for search API integration, demonstrating best practices for tool schema declaration, error handling, and credential management. Includes inline code comments explaining MCP protocol patterns, tool registration flow, and transport mechanisms. Provides example client configurations and integration patterns in README documentation, enabling developers to understand how to build similar MCP servers for other APIs.