This document provides a high-level introduction to the Brave Search MCP Server, its purpose, core architecture, and capabilities. For detailed installation instructions, see Installation. For architectural deep-dives, see Architecture. For tool-specific documentation, see Search Tools.
The Brave Search MCP Server is a Model Context Protocol server implementation that bridges AI assistants with Brave Search API functionality. The server implements the Server class from @modelcontextprotocol/sdk and exposes six search tools: brave_web_search, brave_local_search, brave_image_search, brave_video_search, brave_news_search, and brave_summarizer.
The entry point at src/index.ts initializes the program (Commander instance) which parses CLI arguments and selects between two transport implementations: StdioServerTransport (default) for subprocess communication or StreamableHTTPServerTransport for HTTP mode. The default transport changed to STDIO in version 2.0 to follow MCP ecosystem conventions.
Target use cases include:
Sources: README.md1-3 package.json2-5 server.json3-4 src/index.ts1-32 src/protocols/stdio.ts1-14 src/protocols/http.ts1-77
| Property | Value |
|---|---|
| NPM Package | @brave/brave-search-mcp-server |
| MCP Registry Name | io.github.brave/brave-search-mcp-server |
| Current Version | 2.0.72 |
| License | MIT |
| Repository | https://github.com/brave/brave-search-mcp-server |
| Primary Language | TypeScript |
| Entry Point | dist/index.js (bin) |
| Module Export | dist/server.js |
| Default Transport | STDIO via StdioServerTransport |
| MCP Schema Version | 2025-12-11 |
Sources: package.json2-24 server.json2-9
System Architecture with Code Entities
The following diagram maps system components to their code implementations, showing the complete request flow from client to Brave API:
Sources: src/index.ts1-32 src/config.ts1-145 src/server.ts1-32 src/tools/index.ts1-9 src/protocols/stdio.ts1-14 src/protocols/http.ts1-77 src/BraveAPI/index.ts1-108
| Component | File Path | Key Functions/Classes | Responsibility |
|---|---|---|---|
| Entry Point | src/index.ts | program (Commander), main() | CLI argument parsing, transport mode selection, server startup |
| Configuration | src/config.ts | configSchema, parseConfig(), isToolPermittedByUser() | Zod-based validation, environment variable loading, tool permission filtering |
| Server Factory | src/server.ts | createMcpServer(), Server.setRequestHandler() | MCP Server instance creation, tool registration, request routing |
| STDIO Transport | src/protocols/stdio.ts | StdioServerTransport | stdin/stdout pipe communication for Claude Desktop, VS Code |
| HTTP Transport | src/protocols/http.ts | Express app, StreamableHTTPServerTransport, transports Map | HTTP server on port 8080, session management, stateless tool listing |
| Tool Registry | src/tools/index.ts | tools Map, getTools() | Central tool registration and discovery |
| API Client | src/BraveAPI/index.ts | issueRequest(), BRAVE_BASE_URL | HTTP client for Brave Search API, rate limiting, error handling |
Sources: src/index.ts1-32 src/config.ts1-145 src/server.ts1-32 src/protocols/stdio.ts1-14 src/protocols/http.ts1-77 src/tools/index.ts1-9 src/BraveAPI/index.ts1-108
The server exposes six search tools, each mapping to a specific Brave Search API endpoint:
| Tool Name | Implementation File | API Endpoint | Schema Validation | Key Parameters |
|---|---|---|---|---|
brave_web_search | src/tools/web/index.ts | /res/v1/web/search | webQueryParamsSchema | query (max 400 chars), country, search_lang, result_filter, summary |
brave_local_search | src/tools/local/index.ts | /res/v1/local/pois, /res/v1/local/descriptions | webQueryParamsSchema | query + automatic location filtering |
brave_image_search | src/tools/images/index.ts | /res/v1/images/search | outputSchema (Zod) | query, count (1-200), safesearch |
brave_video_search | src/tools/videos/index.ts | /res/v1/videos/search | videoQueryParamsSchema | query, count (1-50), freshness |
brave_news_search | src/tools/news/index.ts | /res/v1/news/search | newsQueryParamsSchema | query, freshness (default: "pd"), extra_snippets |
brave_summarizer | src/tools/summarizer/index.ts | /res/v1/summarizer/search | summarizerParamsSchema | key (from web search with summary=true), entity_info, inline_references |
Sources: README.md19-98 src/tools/web/index.ts1-147 src/tools/local/index.ts1-159 src/tools/images/index.ts1-69 src/tools/summarizer/index.ts1-112
Tool Dependencies and Schema Sharing
Sources: src/tools/web/params.ts3-202 src/tools/web/index.ts1-147 src/tools/local/index.ts1-159 src/tools/summarizer/index.ts1-112 src/BraveAPI/index.ts1-108 src/constants.ts1-4
The following diagram shows how MCP clients interact with the server and external services:
Integration Flow with Code Entities
Sources: src/protocols/stdio.ts1-14 src/protocols/http.ts1-77 src/server.ts1-32 src/config.ts1-145 README.md146-239 server.json16-28
All API requests to Brave Search require authentication via the BRAVE_API_KEY environment variable or --brave-api-key CLI argument. The configuration is loaded by parseConfig() in src/config.ts and validated against configSchema (Zod schema). The API key is transmitted as an X-Subscription-Token HTTP header in the issueRequest() function at src/BraveAPI/index.ts40-104
The server implements client-side rate limiting with two constraints defined in src/constants.ts1-4:
RATE_LIMIT_PER_SECOND: 1 request per secondRATE_LIMIT_PER_MONTH: 15,000 requests per monthThe rate limiter is implemented in src/BraveAPI/index.ts and maintains request counters that are checked before each API call. Rate limit enforcement occurs before API requests to prevent quota exhaustion. Detailed rate limiting architecture is documented in Rate Limiting.
Sources: README.md101-108 server.json20-26 src/config.ts1-145 src/BraveAPI/index.ts40-104 src/constants.ts1-4
The server employs a sophisticated multi-registry distribution strategy orchestrated through GitHub Actions. A single workflow builds and publishes to five distinct registries simultaneously:
Multi-Registry Release Architecture
Sources: .github/workflows/build-release.yml1-133 marketplace-revision-release.json1-59
| Registry | Authentication Method | Package Format | Target Audience | Special Features |
|---|---|---|---|---|
| NPM | NODE_AUTH_TOKEN secret | JavaScript package | Node.js developers | Immediate npx execution |
| Docker Hub | Username/password | Container image | Container users | Multi-architecture support (amd64, aarch64) |
| AWS ECR | IAM role assumption | Container image | AWS ecosystem | Integration with Bedrock Agentcore |
| MCP Registry | GitHub OIDC | MCP metadata | MCP clients | Tool discovery via Smithery |
| AWS Marketplace | marketplace-catalog API | Product listing | Enterprise customers | Commercial marketplace presence |
The AWS Marketplace integration uses marketplace-revision-release.json which is dynamically updated via jq commands during the CI/CD process to inject current version numbers, release notes, and container URIs before submitting change sets through the AWS Marketplace Catalog API.
Sources: .github/workflows/build-release.yml1-133 marketplace-revision-release.json1-59 README.md136-187 package.json14-19
| Method | Command | Use Case | Prerequisites |
|---|---|---|---|
| NPX Direct | npx -y @brave/brave-search-mcp-server | Zero-install quick start | Node.js 22+ |
| NPM Install | npm install @brave/brave-search-mcp-server | Local development | Node.js 22+ |
| Docker Run | docker run -i --rm mcp/brave-search | Isolated execution | Docker installed |
| Smithery CLI | npx -y @smithery/cli install brave | Automated MCP setup | Node.js 22+ |
| AWS Marketplace | Bedrock Agentcore integration | Enterprise deployment | AWS account |
Sources: README.md136-187 package.json22-24
| Layer | Technology | Version | Purpose | Usage in Codebase |
|---|---|---|---|---|
| Runtime | Node.js | 22.x+ | JavaScript execution environment | Required for all deployment modes |
| Language | TypeScript | 5.9.3 | Type-safe development | Compiled via tsc to dist/ directory |
| MCP SDK | @modelcontextprotocol/sdk | 1.26.0 | MCP protocol implementation | Server, StdioServerTransport, StreamableHTTPServerTransport |
| HTTP Server | Express | 5.2.1 | HTTP transport mode | app.post('/message') in src/protocols/http.ts |
| CLI Parsing | Commander | 14.0.2 | Command-line argument parsing | program instance in src/index.ts |
| Schema Validation | Zod | 4.3.5 | Runtime type validation | configSchema, parameter schemas, output schemas |
| Environment Config | dotenv | 17.2.3 | .env file loading | config() call in src/index.ts |
| Security | jose | 6.1.3 | JWT/JWE operations | Included via @modelcontextprotocol/sdk |
| Security | pkce-challenge | 5.0.0 | OAuth PKCE flows | Included via @modelcontextprotocol/sdk |
| HTTP Middleware | cors | 2.8.5 | Cross-origin resource sharing | HTTP transport CORS policy |
| HTTP Middleware | express-rate-limit | 8.2.1 | API request throttling | HTTP transport protection |
| JSON Validation | ajv | 8.18.0 | JSON Schema validation | Runtime schema enforcement |
| Code Formatting | Prettier | 3.7.4 | Code style enforcement | Pre-commit hook via npm run prepare |
| Build Tool | shx | 0.4.0 | Cross-platform shell commands | chmod +x dist/*.js in build script |
| Tool | Version | Purpose | Usage |
|---|---|---|---|
| @smithery/cli | 2.2.1 | MCP service development | npm run smithery:dev |
| @smithery/sdk | 3.0.1 (peer) | Smithery platform integration | Service registry operations |
| @anthropic-ai/mcpb | 1.1.1 | MCP specification tooling | Build process integration |
| @ngrok/ngrok | 1.5.2 | Local tunneling | Development HTTP testing |
| tsx | 4.21.0 | TypeScript execution | Watch mode development |
Sources: package.json39-54 package-lock.json865-903 package-lock.json1180-1217 tsconfig.json1-17 README.md256-260
All search operations require an active Brave Search API subscription. The API key must be configured through:
BRAVE_API_KEY--brave-api-key.env file: BRAVE_API_KEY=<key>The API key is transmitted as an X-Subscription-Token header in src/BraveAPI/index.ts40-104 and marked as a secret in server.json20-26 with "isSecret": true.
API Subscription Tiers:
| Tier | Monthly Queries | Features | Tool Availability |
|---|---|---|---|
| Free | 2,000 | Web, image, video, news search | brave_web_search, brave_image_search, brave_video_search, brave_news_search |
| Pro | 15,000+ | All features + local search, AI summaries, extra snippets | All tools including brave_local_search, brave_summarizer |
API Endpoints:
GET https://api.search.brave.com/res/v1/web/searchGET https://api.search.brave.com/res/v1/local/poisGET https://api.search.brave.com/res/v1/local/descriptionsGET https://api.search.brave.com/res/v1/images/searchGET https://api.search.brave.com/res/v1/videos/searchGET https://api.search.brave.com/res/v1/news/searchGET https://api.search.brave.com/res/v1/summarizer/searchSources: README.md101-108 server.json20-26 src/config.ts25-145 src/BraveAPI/index.ts1-108
AWS Bedrock Agentcore:
BRAVE_MCP_STATELESS=trueClaude Desktop:
claude_desktop_config.jsonVS Code:
.vscode/mcp.json or User SettingsSources: README.md146-239 src/protocols/http.ts1-77 src/protocols/stdio.ts1-14
All deployment methods require:
The configSchema in src/config.ts validates that braveApiKey is a non-empty string during initialization.
Sources: README.md101-108 server.json20-26 src/config.ts25-145
Current Version: 2.0.72
Major Version 2.0 Changes:
brave_image_search response structure modified to remove base64-encoded image dataTo continue using HTTP transport in version 2.x, set BRAVE_MCP_TRANSPORT=http environment variable or use --transport http CLI argument.
Sources: README.md5-15 package.json4
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.