Search MCP

The Universal MCP Server exposes tools for Brave Search API integration, enabling web search, local POI search, and rich search results through the Model Context Protocol.

Installation

Prerequisites

• Node.js 18+
• Set SEARCH_MCP_API_KEY in your environment with your Brave Search API key

Get an API key

• Sign up at Brave Search API
• Navigate to API Keys section to create a new API key
• Even for the Free plan, you need to subscribe (you won't be charged)

Build locally

cd /path/to/search-mcp
npm i
npm run build

Setup: Claude Code (CLI)

Use this one-liner (replace with your real values):

claude mcp add "Search MCP" -s user -e SEARCH_MCP_API_KEY="BSA-your-real-key" -- npx search-mcp

To remove:

claude mcp remove "Search MCP"

Setup: Cursor

Create .cursor/mcp.json in your client (do not commit it here):

{
  "mcpServers": {
    "search-mcp": {
      "command": "npx",
      "args": ["search-mcp"],
      "env": { "SEARCH_MCP_API_KEY": "BSA-your-real-key" },
      "autoStart": true
    }
  }
}

Other Clients and Agents

Install via URI or CLI:

code --add-mcp '{"name":"search-mcp","command":"npx","args":["search-mcp"],"env":{"SEARCH_MCP_API_KEY":"BSA-your-real-key"}}'

Similar to VS Code, use code-insiders command:

code-insiders --add-mcp '{"name":"search-mcp","command":"npx","args":["search-mcp"],"env":{"SEARCH_MCP_API_KEY":"BSA-your-real-key"}}'

Follow the MCP installation guide and add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "search-mcp": {
      "command": "npx",
      "args": ["search-mcp"],
      "env": { "SEARCH_MCP_API_KEY": "BSA-your-real-key" }
    }
  }
}

• Command: npx
• Args: ["search-mcp"]
• Env: SEARCH_MCP_API_KEY=BSA-your-real-key

• Type: STDIO
• Command: npx
• Args: search-mcp
• Enabled: true
• Environment variables: SEARCH_MCP_API_KEY=BSA-your-real-key

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "search-mcp": {
      "type": "local",
      "command": ["npx", "search-mcp"],
      "enabled": true,
      "env": {
        "SEARCH_MCP_API_KEY": "BSA-your-real-key"
      }
    }
  }
}

Add a new MCP and paste the standard JSON config:

{
  "command": "npx",
  "args": ["search-mcp"],
  "env": { "SEARCH_MCP_API_KEY": "BSA-your-real-key" }
}

See Windsurf MCP documentation and add the following configuration:

{
  "mcpServers": {
    "search-mcp": {
      "command": "npx",
      "args": ["search-mcp"],
      "env": { "SEARCH_MCP_API_KEY": "BSA-your-real-key" }
    }
  }
}

Setup: Codex (TOML)

Add the following to your Codex TOML configuration.

Example (Serena reference):

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

This server (minimal):

[mcp_servers.search-mcp]
command = "npx"
args = ["search-mcp"]
# Optional environment variables:
# SEARCH_MCP_API_KEY = "BSA-your-real-key"
# MCP_NAME = "search-mcp"

Configuration (Env)

• SEARCH_MCP_API_KEY: Your Brave Search API subscription token (required)
• MCP_NAME: Server name override (default: search-mcp)

Available Tools

web_search

Search the web using Brave Search API.

Inputs:

• q (string, required): The search query
• country (string, optional): Country code (e.g., "US", "JP")
• search_lang (string, optional): Search language (e.g., "en", "ja")
• count (number, optional): Number of results (default: 10, max: 20)
• offset (number, optional): Pagination offset
• safesearch (string, optional): Safe search level - "off", "moderate", or "strict"
• freshness (string, optional): Filter by age - "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year)
• enable_rich_callback (boolean, optional): Enable rich search results callback

Outputs: JSON object containing web search results with titles, descriptions, URLs, and optional rich content hints.

local_pois

Get detailed information about local points of interest.

Inputs:

• ids (array of strings, required): Location IDs from web search (max 20)

Outputs: JSON object with enriched location data including pictures and related web results.

local_descriptions

Get AI-generated descriptions for locations.

Inputs:

• ids (array of strings, required): Location IDs from web search (max 20)

Outputs: JSON object with AI-generated descriptions for each location.

rich_search

Fetch rich search results (weather, sports, stocks, etc.).

Inputs:

• callback_key (string, required): Callback key from web search response (found in rich.hint.callback_key)

Outputs: JSON object with rich vertical data (weather forecasts, sports scores, stock prices, etc.).

For detailed schemas, see src/index.ts.

Example invocation (MCP tool call)

Basic web search:

{
  "name": "web_search",
  "arguments": {
    "q": "TypeScript tutorial",
    "country": "US",
    "search_lang": "en",
    "count": 5
  }
}

Local search workflow:

// Step 1: Search for locations
{
  "name": "web_search",
  "arguments": {
    "q": "coffee shops in San Francisco"
  }
}

// Step 2: Get detailed POI info using IDs from step 1
{
  "name": "local_pois",
  "arguments": {
    "ids": ["1520066f3f39496780c5931d9f7b26a6", "d00b153c719a427ea515f9eacf4853a2"]
  }
}

// Step 3: Get AI descriptions for locations
{
  "name": "local_descriptions",
  "arguments": {
    "ids": ["1520066f3f39496780c5931d9f7b26a6"]
  }
}

Rich search workflow:

// Step 1: Enable rich callback in web search
{
  "name": "web_search",
  "arguments": {
    "q": "weather in Tokyo",
    "enable_rich_callback": true
  }
}

// Step 2: Use callback_key from response to get rich data
{
  "name": "rich_search",
  "arguments": {
    "callback_key": "86d06abffc884e9ea281a40f62e0a5a6"
  }
}

Troubleshooting

• 401 auth errors: Check that SEARCH_MCP_API_KEY is set correctly with a valid Brave Search API token
• Module not found errors: Ensure Node.js 18+ is installed (node -v)
• Build errors: Run npm install followed by npm run build in the project directory
• Local testing: After building, test with npx search-mcp or node build/index.js
• Inspect publish artifacts: Run npm pack --dry-run to see what files would be included in the npm package

References

• Brave Search API Documentation
• Brave Web Search API
• MCP SDK Documentation
• MCP Architecture
• MCP Server Concepts
• MCP Server Specification

Name Consistency & Troubleshooting

• Always use CANONICAL_ID (search-mcp) for identifiers and keys.
• Use CANONICAL_DISPLAY (Search MCP) only for UI labels.
• Do not mix different names across clients.

Consistency Matrix

• npm package name → search-mcp
• Binary name → search-mcp
• MCP server name (SDK metadata) → search-mcp
• Env default MCP_NAME → search-mcp
• Client registry key → search-mcp
• UI label → Search MCP

Conflict Cleanup

• Remove any old entries with different names (e.g., "SearchMCP", "brave-search") and re-add with search-mcp.
• Ensure global .mcp.json or client registries only use search-mcp for keys.
• Cursor: Configure in the UI only. This project does not include .cursor/mcp.json.

Example

Correct:

{
  "mcpServers": {
    "search-mcp": {
      "command": "npx",
      "args": ["search-mcp"]
    }
  }
}

Incorrect:

{
  "mcpServers": {
    "SearchMCP": {  // ❌ Wrong key - will conflict
      "command": "npx",
      "args": ["search-mcp"]
    }
  }
}