webseek

name	webseek
description	Unified multi-provider web search via the webseek CLI, MCP server, and library (OpenAI, Google Custom Search, Gemini). Use when running a web search from the terminal, embedding web search into a program, or wiring webseek as an MCP web_search tool.

webseek

Web search using the API keys of multiple providers behind a single, unified interface. Bring whichever provider key you already have and search the web — either from your terminal (CLI mode) or from an MCP client such as an editor or agent (MCP server mode). Both modes share the same core search logic.

Providers

webseek normalizes two fundamentally different kinds of "web search":

Provider	Kind	Output
google	SERP-style (Google Custom Search)	a ranked list of links
openai	LLM-grounded (Responses API web_search)	a synthesized answer + citations
gemini	LLM-grounded (Grounding with Google Search)	a synthesized answer + citations

The Gemini provider supports two backends that share the same request/response shape: the Gemini Developer API (gemini-api, default) and Vertex AI express mode (vertex-express).

Install

npm install -g webseek      # install the CLI globally
npx webseek "..." -p google   # or run without installing

Build from source

pnpm install
pnpm build      # dual-format (ESM + CJS) build via tsdown; exposes the `webseek` bin

During development you can run without building via pnpm dev -- <args> (runs the TypeScript source through tsx).

CLI mode

webseek <query...> --provider <openai|google|gemini> [options]

Options:

Flag	Description
-p, --provider <name>	openai | google | gemini (required)
-n, --max-results <n>	Desired number of results (SERP providers)
-m, --model <name>	Model override (openai, gemini)
--gemini-backend <b>	gemini-api (default) | vertex-express
--json	Emit normalized JSON instead of text
--raw	Include the provider's raw response

Examples:

webseek "best static site generators 2026" -p google -n 5
webseek "summarize the latest TypeScript release" -p openai
webseek "who won euro 2024" -p gemini --gemini-backend vertex-express --json

MCP server mode

Start a Model Context Protocol server over stdio that exposes a single web_search tool:

webseek mcp

Register it with an MCP client, e.g.:

{
  "mcpServers": {
    "webseek": {
      "command": "webseek",
      "args": ["mcp"],
      "env": { "GEMINI_API_KEY": "..." },
    },
  },
}

The web_search tool accepts { query, provider, maxResults?, model?, geminiBackend?, includeRaw? } and returns the normalized result as JSON.

Library (programmatic API)

webseek is published as a dual-format package (ESM + CJS), so it can be imported as a library in addition to running as a CLI/MCP server:

import { runSearch, WebseekError } from "webseek";

const result = await runSearch({ provider: "google", query: "best static site generators 2026" });
console.log(result.results);

CommonJS consumers can require it the same way:

const { runSearch } = require("webseek");

To embed the web_search tool into your own MCP server, use the createWebSearchTool factory exported from the same entry point.

Authentication

API keys are read from environment variables only (never from flags), so they don't leak into shell history or process listings.

Provider	Environment variables
openai	OPENAI_API_KEY
google	GOOGLE_API_KEY, GOOGLE_CSE_CX (Programmable Search Engine ID)
gemini (gemini-api)	GEMINI_API_KEY (falls back to GOOGLE_API_KEY)
gemini (vertex-express)	VERTEX_API_KEY

Caveats

• Google Custom Search is closed to new customers. Existing customers must migrate before 2027-01-01. Treat this provider as the most at-risk.
• Google Custom Search returns at most 100 results (10 per request); large --max-results values paginate and consume more quota.
• Gemini grounding requires displaying Google Search Suggestions per its terms. As a CLI we surface the queries the model ran on the Searches: line; the source URIs Gemini returns are temporary redirect links.