@greatnxy/web-search-mcp

A focused MCP server that gives your MCP client a straightforward way to search the web and receive structured results through a single tool: web_search.

This server integrates with Tavily and Brave because both services provide free usage options, making it practical to get started with web search. See their plans and pricing: Tavily Plans & Pricing · Brave Search API Plans.

Install and run

npm install
$env:TAVILY_API_KEY = "tvly-..."
$env:BRAVE_API_KEY = "BSA..."
npm run build
npm start

For key rotation within each provider, use comma-separated values.

$env:TAVILY_API_KEYS = "tvly-first,tvly-second"
$env:BRAVE_API_KEYS = "brave-first,brave-second"

Keys are chosen randomly from each provider's currently available pool. A 429 pauses that Key until the provider's response says it can be retried. An authentication or quota error removes the Key until the server is restarted.

Related MCP server: AI Makerspace MCP Demo Server

VS Code configuration

Create or edit your MCP configuration and keep secrets in password inputs:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tavily-api-key",
      "description": "Tavily API key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "brave-api-key",
      "description": "Brave Search API key",
      "password": true
    }
  ],
  "servers": {
    "web-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@greatnxy/web-search-mcp"],
      "env": {
        "TAVILY_API_KEY": "${input:tavily-api-key}",
        "BRAVE_API_KEY": "${input:brave-api-key}"
      }
    }
  }
}

Environment variables

Search behavior

The gateway calls Tavily first. It calls Brave when Tavily returns no results, times out, is unavailable, is rate-limited, or reports exhausted plan/PAYG quota. Each request randomly selects an available key from the chosen provider's pool.

Tool input and output

web_search accepts query, optional max_results (1–20), freshness (day, week, month, year), ISO country code, and include/exclude domain lists.

It returns query, selected provider, fallback state and reason, providers tried, and ranked title/url/snippet results.

Verify

npm run check
npm test
npm run build