Provides access to Brave's search APIs including web search, local points of interest (POIs), location descriptions, and rich search results with support for filtering by country, safe search settings, and content freshness
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Earch MCP find nearby coffee shops open now"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The Universal MCP Server exposes tools for your workflows and is designed for prompt-first usage in MCP-compatible clients.
Node.js 18+
Set EARCH_MCP_API_KEY in your environment (or BRAVE_API_KEY)
If your tools require an external API, obtain a key from the provider’s docs/console.
Otherwise, you can skip this step.
cd /path/to/earch-mcp
npm i
npm run buildRelated MCP server: Brave Search MCP Server
Use this one-liner (replace with your real values):
claude mcp add Earch MCP -s user -e EARCH_MCP_API_KEY="sk-your-real-key" -- npx earch-mcpTo remove:
claude mcp remove Earch MCPCreate .cursor/mcp.json in your client (do not commit it here):
{
"mcpServers": {
"earch-mcp": {
"command": "npx",
"args": ["earch-mcp"],
"env": { "EARCH_MCP_API_KEY": "sk-your-real-key" },
"autoStart": true
}
}
}Install via URI or CLI:
code --add-mcp '{"name":"earch-mcp","command":"npx","args":["earch-mcp"],"env":{"EARCH_MCP_API_KEY":"sk-your-real-key"}}'Follow the MCP install guide and reuse the standard config above.
Command: npx
Args: ["earch-mcp"]
Env: EARCH_MCP_API_KEY=sk-your-real-key
Type: STDIO
Command: npx
Args: earch-mcp
Enabled: true
Example ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"earch-mcp": {
"type": "local",
"command": ["npx", "earch-mcp"],
"enabled": true
}
}
}Add a new MCP and paste the standard JSON config.
See docs and reuse the standard config above.
Example (Serena):
[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]This server (minimal):
[mcp_servers.earch-mcp]
command = "npx"
args = ["earch-mcp"]
# Optional environment variables:
# EARCH_MCP_API_KEY = "sk-your-real-key"
# MCP_NAME = "earch-mcp"EARCH_MCP_API_KEY: Your API key (or BRAVE_API_KEY)
MCP_NAME: Server name override (default: earch-mcp)
web.search
inputs: { q: string, count?: number (<=50), country?: string, safesearch?: "off"|"moderate"|"strict", freshness?: "pd"|"pw"|"pm"|"py" }
outputs: JSON from Brave Web Search API
local.pois
inputs: { ids: string[1..20] }
outputs: JSON from Brave Local POIs API
local.descriptions
inputs: { ids: string[1..20] }
outputs: JSON from Brave Local Descriptions API
web.rich
inputs: { q: string }
outputs: JSON containing hint and rich callback result
{
"tool": "web.search",
"arguments": { "q": "brave search" }
}401 auth errors: check EARCH_MCP_API_KEY or BRAVE_API_KEY
Ensure Node 18+
Local runs: npx earch-mcp after npm run build
Inspect publish artifacts: npm pack --dry-run
Architecture: https://modelcontextprotocol.io/docs/learn/architecture
Server Concepts: https://modelcontextprotocol.io/docs/learn/server-concepts
Server Spec: https://modelcontextprotocol.io/specification/2025-06-18/server/index
Brave Search API: https://api.search.brave.com/res/v1/web/search
Brave Local API: https://api.search.brave.com/res/v1/local/pois
Brave Rich API: https://api.search.brave.com/res/v1/web/rich
Always use CANONICAL_ID (earch-mcp) for identifiers and keys.
Use CANONICAL_DISPLAY (Earch MCP) only for UI labels.
Do not mix legacy keys after registration.
Consistency Matrix:
npm package name → earch-mcp
Binary name → earch-mcp
MCP server name (SDK metadata) → earch-mcp
Env default MCP_NAME → earch-mcp
Client registry key → earch-mcp
UI label → Earch MCP
Conflict Cleanup:
Remove any stale keys (e.g., old display names) and re-add with earch-mcp only.
Cursor: configure in the UI; this project intentionally omits .cursor/mcp.json.
Brave Local Search AI descriptions: fetch descriptions for up to 20 location ids
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions fetching descriptions for location IDs with a limit of 20, but doesn't specify what 'descriptions' contain (e.g., text, metadata), how results are returned, error handling, or any rate limits. This leaves significant gaps for a tool with one required parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key action ('fetch descriptions') and constraint ('up to 20'). There's no wasted verbiage, though it could be slightly more structured (e.g., separating purpose from limitations).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what 'descriptions' entail (e.g., text summaries, attributes), how results are formatted, or any behavioral nuances. For a tool fetching data with a required parameter, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It only implies that 'ids' are 'location ids' and there's a limit of 20, but doesn't explain what format these IDs should be (e.g., numeric, alphanumeric), where they come from, or what happens if invalid IDs are provided. This adds minimal value beyond the schema's structural constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch' and the resource 'descriptions for location ids', specifying the scope 'up to 20'. It distinguishes from siblings like 'local.pois' (likely points of interest) and web tools by focusing on descriptions for location IDs. However, it doesn't explicitly differentiate from all siblings (e.g., 'web.rich' might also provide descriptions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'local.pois' (which might return different location data) or 'web.search' (which might search more broadly). There's no context about prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brave Local Search POIs: fetch extra info for up to 20 location ids
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the action ('fetch extra info') and a constraint ('up to 20 location ids'), but lacks critical details such as what type of information is returned, whether this is a read-only operation, potential rate limits, authentication requirements, or error handling. The description is too vague to fully inform agent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence that efficiently communicates the core functionality and key constraint. Every word earns its place, with no redundant or unnecessary information, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (1 parameter with 0% schema coverage, no annotations, and no output schema), the description is insufficiently complete. It fails to explain what 'extra info' includes, the format of the response, error conditions, or how this tool relates to siblings. For a data-fetching tool, this leaves too many unknowns for reliable agent operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It only vaguely references 'location ids' for the 'ids' parameter without explaining what format these IDs should be (e.g., numeric, alphanumeric), where they come from, or what constitutes a valid location ID. This leaves significant ambiguity about parameter meaning and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('fetch extra info') and resources ('location ids'), and specifies the scope ('up to 20'). It distinguishes itself from generic search tools by focusing on supplementary data for existing IDs rather than discovery. However, it doesn't explicitly differentiate from sibling tools like local.descriptions, which might offer similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance, only implying this tool should be used when you have location IDs and need additional information. It offers no explicit guidance on when to use this versus alternatives like local.descriptions or web.search, nor does it mention prerequisites or constraints beyond the ID count limit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brave Rich Search via callback flow. First enables rich callback, then fetches rich data
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions a two-step process (enable callback, then fetch data) which adds some context about the tool's workflow. However, it doesn't disclose important behavioral traits like whether this is a read/write operation, authentication requirements, rate limits, error conditions, or what happens during the callback flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point with two clear sentences. It efficiently describes the two-step process without unnecessary elaboration. However, it could be more front-loaded with the core purpose before detailing the implementation flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, 0% schema description coverage, and no output schema, the description is inadequate. It doesn't explain what 'rich data' means, what the callback flow entails, what format results are returned in, or how this differs from the simpler web.search sibling tool. The description leaves too many open questions about the tool's behavior and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. The description doesn't mention the 'q' parameter at all, nor does it explain what this parameter represents (presumably a search query). No additional semantic information is provided beyond what the bare schema indicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool performs 'Brave Rich Search via callback flow' with two steps: enabling rich callback and fetching rich data. This provides a general purpose but lacks specificity about what 'rich data' entails or what resource is being searched. It doesn't clearly distinguish from sibling tools like web.search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like web.search. The description mentions a 'callback flow' which might imply specific usage scenarios, but doesn't state when this approach is preferred over direct search methods or what distinguishes it from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brave Web Search: returns results for query q
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| count | No | ||
| country | No | ||
| safesearch | No | ||
| freshness | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns search results but lacks critical details: it doesn't mention rate limits, authentication needs, pagination, error handling, or whether it's read-only or mutative. For a web search tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the tool's core purpose ('Brave Web Search: returns results for query q'), making it easy to scan. Every part of the sentence earns its place by specifying the service and action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 2 with enums, no output schema, and no annotations), the description is incomplete. It doesn't explain return values, error cases, or behavioral constraints. For a search tool with multiple optional parameters and no structured guidance, the description should provide more context to help the agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 5 parameters are documented in the schema. The description only mentions 'query q', covering 1 of 5 parameters. It doesn't explain the semantics of count, country, safesearch, or freshness, nor does it clarify enum values (e.g., what 'pd' means for freshness). The description fails to compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'returns results for query q' using Brave Web Search. It specifies the verb ('returns results'), resource ('Web Search'), and distinguishes it from siblings like local.descriptions and local.pois by focusing on web search. However, it doesn't explicitly differentiate from web.rich, which might be a similar web-related tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose web.search over web.rich or local tools, nor does it specify any prerequisites, exclusions, or contextual usage scenarios. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0local.descriptions1 field changedInput schema / additionalPropertiesAdded value: +falselocal.pois1 field changedInput schema / additionalPropertiesAdded value: +falseweb.rich1 field changedInput schema / additionalPropertiesAdded value: +falseweb.search1 field changedInput schema / additionalPropertiesAdded value: +falselocal.descriptionslocal.poisweb.richweb.searchScored across 4 tools
The tools are mostly distinct in purpose, with clear separation between local search (descriptions vs. POIs) and web search (rich vs. standard). However, the distinction between 'local.descriptions' and 'local.pois' could be slightly ambiguous without more context about what each returns, as both handle location IDs.
Naming is mostly consistent with a clear prefix pattern (local. vs. web.) and descriptive suffixes. Minor deviations exist, such as 'web.rich' being less conventional than 'web.search', but overall the naming is predictable and readable.
With 4 tools, the count is well-scoped for a search-focused server. Each tool appears to serve a specific function without redundancy, making the set manageable and appropriate for the domain of search operations.
The toolset covers basic search functionalities (local and web), but there are notable gaps. For example, there is no tool for updating or deleting search data, and advanced features like filtering or sorting are missing, which could limit agent workflows in a comprehensive search domain.
Visit https://brave.com/search/api/ for a free API key. Search the web, local businesses, images,…
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Web search, news, page retrieval, sitemaps, and trending topics through Search1API.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
