npm package: @keitaro_aigc/search-mcp
Description: MCP server for Brave Search API integration
Latest version: 1.0.0

# 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](https://brave.com/search/api/)
- Navigate to [API Keys section](https://api.search.brave.com/app/keys) to create a new API key
- Even for the Free plan, you need to subscribe (you won't be charged)

### Build locally
```bash
cd /path/to/search-mcp
npm i
npm run build
```

## Setup: Claude Code (CLI)

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

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

To remove:

```bash
claude mcp remove "Search MCP"
```

## Setup: Cursor

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

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

## Other Clients and Agents

<details>
<summary>VS Code</summary>

Install via URI or CLI:

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

</details>

<details>
<summary>VS Code Insiders</summary>

Similar to VS Code, use `code-insiders` command:

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

</details>

<details>
<summary>Claude Desktop</summary>

Follow the [MCP installation guide](https://modelcontextprotocol.io/quickstart/user) and add to your config file:

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

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

</details>

<details>
<summary>LM Studio</summary>

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

</details>

<details>
<summary>Goose</summary>

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

</details>

<details>
<summary>opencode</summary>

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

```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"
      }
    }
  }
}
```

</details>

<details>
<summary>Qodo Gen</summary>

Add a new MCP and paste the standard JSON config:

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

</details>

<details>
<summary>Windsurf</summary>

See [Windsurf MCP documentation](https://docs.codeium.com/windsurf/mcp) and add the following configuration:

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

</details>

## Setup: Codex (TOML)

Add the following to your Codex TOML configuration.

Example (Serena reference):

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

This server (minimal):

```toml
[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:
```json
{
  "name": "web_search",
  "arguments": {
    "q": "TypeScript tutorial",
    "country": "US",
    "search_lang": "en",
    "count": 5
  }
}
```

### Local search workflow:
```json
// 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:
```json
// 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](https://brave.com/search/api/)
- [Brave Web Search API](https://api.search.brave.com/app/documentation/web-search/get-started)
- [MCP SDK Documentation](https://modelcontextprotocol.io/docs/sdks)
- [MCP Architecture](https://modelcontextprotocol.io/docs/learn/architecture)
- [MCP Server Concepts](https://modelcontextprotocol.io/docs/learn/server-concepts)
- [MCP Server Specification](https://modelcontextprotocol.io/specification/2025-06-18/server/index)

## 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:**
```json
{
  "mcpServers": {
    "search-mcp": {
      "command": "npx",
      "args": ["search-mcp"]
    }
  }
}
```

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