dyoshikawa 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-resultsvalues 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.