@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

[!WARNING] If you want to use only Brave's free quota, be sure to set a usage limit for your Brave Search account. Configure it in Brave Search usage limits.

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. Invalid requests do not pause or remove otherwise available keys.

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

| Variable | Default | Purpose | | --- | --- | --- | | TAVILY_API_KEY / TAVILY_API_KEYS | required | One key or a comma-separated Tavily key pool. | | BRAVE_API_KEY / BRAVE_API_KEYS | required | One key or a comma-separated Brave key pool. | | SEARCH_TIMEOUT_MS | 10000 | Tavily and Brave HTTP request timeout. |

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.

Invalid parameters are not retried and do not trigger fallback. Tavily HTTP 400/422 and Brave HTTP 422 are classified as invalid_request. Local query-limit errors explain how to shorten the query or reduce filters; other provider error bodies are not exposed. Change the query or filters rather than retrying an invalid request unchanged.

Tool input and output

Use web_search for up-to-date information or source links. Keep each query focused on one topic; split complex questions into separate searches rather than putting long task instructions in query. Provider selection is automatic, with no provider-selection parameter.

| Parameter | Usage | | --- | --- | | query | Required, trimmed, nonempty, at most 400 characters. Use the domain parameters instead of repeating site: operators here. | | max_results | Optional, 1–20; defaults to 5. | | freshness | Optional: day, week, month, or year. Filters by publication or last-update date within that period; pages with undetectable dates may still appear. | | country | Optional, uppercase or lowercase: AR, AU, AT, BE, BR, CA, CL, DK, FI, FR, DE, GR, IN, ID, IT, JP, KR, MY, MX, NL, NZ, NO, CN, PL, PT, PH, RU, SA, ZA, ES, SE, CH, TW, TR, GB, US. These 36 codes are supported by both providers. This is a geographic preference, not a result-language guarantee. If omitted, Brave defaults to US and Tavily receives no country filter. | | include_domains | Optional, up to 20 bare domains or subdomains, without protocols, paths, or wildcards. Results may come from any listed domain. | | exclude_domains | Optional, up to 20 bare domains or subdomains, without protocols, paths, or wildcards. Excludes the listed domains. |

Before any provider request, the full Brave query, including domain operators, is checked against limits of 600 characters and 75 whitespace-separated words. Domain filters consume this budget: Brave includes domains with site:example.com OR site:other.com and excludes them with NOT site:example.com. Shorten the query or reduce filters if a limit is exceeded. The local whitespace count cannot exactly match Brave's unpublished word-counting rules. Brave's search operators are experimental, so filtering is not guaranteed to produce the same results as Tavily.

The tool returns the query, the provider that supplied the results, and ranked title/url/snippet search summaries, not full-page content.

Provider references: Brave Web Search API, Brave search operators, and Tavily Search.

Verify

npm run check
npm test
npm run build