search-boost-mcp

Multi-engine web search MCP server for coding agents. One CLI install wires it into Cursor, Cursor CLI, Codex, Claude Code, Grok Build, and Antigravity.

search-boost family

Project For Link

search-boost (this repo) Cursor · Codex · Claude · Grok · Antigravity via MCP you are here

dsh-search-boost DeepSeek Harness bundle plugin GitHub · npm

pi-search-boost pi extension GitHub · npm

Search engines are vendored in lib/search/ (originally from dsh-search-boost): on the free layer, Bing, DuckDuckGo, Yahoo, and Exa-free run in parallel; the api layer adds Antigravity CLI (when available) and whichever keyed Tavily / Brave / Exa engines you configure (one key is enough; all three recommended for best fusion). Also included: X/Twitter fallback, Jina page fetch, and deep-research rounds.

中文文档 → README_zh.md

Install (recommended)

Requires Node ≥ 22.13.

npm install -g search-boost-mcp
search-boost setup          # interactive: keys → layer → agents
# or non-interactive:
search-boost install -y     # all detected agents

Restart each agent after install so MCP reloads.

Upgrade

Already using search-boost-mcp? Update the global CLI, then refresh agent configs (keys/layer under ~/.search-boost/ are kept):

npm install -g search-boost-mcp@latest
search-boost install -y                 # all detected agents
# or pick targets, e.g. Grok one-step (plugin + config when grok on PATH):
search-boost install -t grok -y --auto-allow
search-boost doctor

Restart each agent after reinstall. Config lazy-migrates from older flat ~/.search-boost-*.json paths on first write.

One-liners by agent

search-boost install -t cursor -y
search-boost install -t codex,claude -y --auto-allow
search-boost install -t grok -y --auto-allow   # plugin + config when grok CLI on PATH
search-boost install -t antigravity --workspace --auto-allow -y

Preview without writing: search-boost install --dry-run -y

Verify install

search-boost doctor          # health checks (offline, pass/warn/fail)
search-boost doctor --json   # machine-readable report for CI/scripts
search-boost status          # install dashboard (keys, layer, agents)

Exit codes: 0 healthy · 1 failure (or warnings with --strict) · 2 warnings only.

Optional: search-boost doctor --probe adds live search smoke (needs network; Phase 2).

Then confirm in your agent:

Agent	Quick check
Cursor	Settings → MCP → `search-boost` connected; tools listed
Cursor CLI	Same MCP entry in `~/.cursor/mcp.json`
Codex	`codex` session lists `mcp__search-boost__*` tools
Claude Code	MCP panel shows `search-boost`; tools callable without deny prompt (if `--auto-allow`)
Grok Build	`grok mcp doctor search-boost` · `grok inspect`
Antigravity	MCP config includes `search-boost`; restart IDE after install

If tools appear but calls fail, run search-boost serve in a terminal to see startup errors.

Install flags (quick reference)

Flag	Effect
`-t`, `--target`	Which agent(s) to wire (`cursor`, `codex`, `claude`, `grok`, `antigravity`, `cursor-cli`, `auto`, `all`)
`-y`, `--yes`	Non-interactive: skips keys/layer wizard, uses `--target=auto`, implies `--auto-allow` and `--replace-native`
`-t` without `-y`	Still non-interactive for that target and still replaces native search by default — but does not imply `--auto-allow`; add it explicitly if you want no permission prompts
`--auto-allow`	Pre-approve search-boost MCP tools in agent config (Cursor CLI allowlist, Codex `default_tools_approval_mode`, Claude/Grok/Antigravity permission rules) so the agent does not prompt every session
`--replace-native` / `--keep-native`	Disable or keep built-in web search where the agent supports a switch (Codex `web_search`, Claude `WebSearch`). Default is replace when non-interactive
`--scope user\|project\|all`	Grok only: user (`~/.grok`), project (`.grok/` in cwd), or both on uninstall
`--skip-grok-plugin`	Grok only: skip bundled `grok plugin install`; still writes config.toml, rule, and skill
`--dry-run`	Print actions without writing files

For full onboarding (API keys + layer choice), run search-boost setup or search-boost install without -y.

Uninstall

search-boost uninstall -t codex -y
search-boost uninstall -t cursor,codex,claude -y

Uninstall removes only search-boost-owned blocks (marked MCP entries, skills, hooks, permission rules). Where the agent supports it, native web search is restored (Codex top-level web_search, Claude WebSearch deny) unless you used --keep-native at install time or had pre-existing unmarked settings. Config files created solely for search-boost are unlinked when empty after cleanup. For Grok, plugin removal via grok plugin uninstall is best-effort (warns and continues if the CLI is missing or uninstall fails). Preview: --dry-run.

What you get

MCP tool	Purpose
`fused_search`	Multi-engine parallel search, dedupe, cross-ranking
`fetch_page`	Full page text (Jina + HTML fallback, optional `focus`)
`x_search`	X/Twitter keyword / user / thread
`deep_research`	One round per call — repeat with `suggested_queries` until gaps empty, then synthesize (~3 rounds max)
`search_layer`	Show or set `free` (keyless) vs `api` (keyed engines)
`search_stats`	Cache hits, engine availability, diagnostics

Also: resource search-boost://policy · prompt search_routing

Layers

free — Bing + DuckDuckGo + Yahoo + Exa-free; no API keys.
api — free-layer engines plus Antigravity CLI (when available) and any of Tavily / Brave / Exa that you configure (one key works; all three recommended for best cross-engine fusion)

Keys: search-boost config keys → ~/.search-boost/config/keys.json (flat ~/.search-boost-keys.json and legacy ~/.dsh-search-boost-keys.json still read; or env TAVILY_API_KEY, BRAVE_API_KEY, EXA_API_KEY). Optional routing: enabledEngines: ["exa"] or "engines": { "brave": { "enabled": false } } in the keys file.

Config layout: runtime data lives under ~/.search-boost/ — config/ (keys, layer, xauth), cache/ (xguest token), state/ (Antigravity workspace registry). First write lazy-migrates from flat ~/.search-boost-*.json and legacy ~/.dsh-* files (old copies kept). Override base: SEARCH_BOOST_HOME; per-file: SEARCH_BOOST_*_FILE.

Obtain keys: Tavily · Brave Search API · Exa

X/Twitter auth (optional): improves official x_search when credentials are present. Stored at ~/.search-boost/config/xauth.json (flat/legacy paths still read) or via XAI_API_KEY. Configure with search-boost config x (see CLI cheat sheet). MCP /x-login and search-boost config x write the same local copy. Override file path: SEARCH_BOOST_XAUTH_FILE.

search-boost config x --show              # xauth status
search-boost config x --import-grok       # import grok CLI login
search-boost config x --set-xai-key KEY   # store XAI API key
search-boost config x --logout            # remove local copy

Config file overrides: SEARCH_BOOST_KEYS_FILE, SEARCH_BOOST_LAYER_FILE, SEARCH_BOOST_XAUTH_FILE (optional env vars pointing at custom paths).

CLI cheat sheet

Command	What it does
`search-boost`	Interactive TUI
`search-boost setup`	Onboarding (keys + layer + install)
`search-boost install` / `uninstall`	Wire MCP + prompts into agents
`search-boost serve`	Run MCP stdio server (used by agents)
`search-boost status`	Keys, layer, X credentials, per-agent configured state
`search-boost doctor [--quick\|--probe] [--json] [--strict]`	Config/agents/engine health checks with pass/warn/fail
`search-boost config keys\|layer\|x\|search`	Keys, default layer, X auth, native-search replace
`search-boost print <agent>`	Print MCP snippet without writing
`search-boost agents`	Machine-readable agent list

Install flags: -t cursor,codex,…|auto|all · -y (non-interactive; implies --auto-allow + --replace-native) · --dry-run · --auto-allow (pre-approve MCP tools — see table above) · --replace-native / --keep-native · --scope user|project|all (Grok) · --skip-grok-plugin (Grok) · --workspace (Antigravity .agents/)

Supported agents

Agent	MCP config	Also installs
Cursor IDE	`~/.cursor/mcp.json`	hook, skill
Cursor CLI	`~/.cursor/mcp.json` (same surface as IDE)	hook, skill (CLI variant), optional CLI auto-allow
Codex CLI	`~/.codex/config.toml`	AGENTS.md, skill
Claude Code	`~/.claude.json`	CLAUDE.md, skill, permissions
Grok Build	`~/.grok/config.toml`	rule, skill, bundled grok-plugin (when `grok` on PATH)
Antigravity	`~/.gemini/config/mcp_config.json`	AGENTS.md, GEMINI.md, skill, optional workspace

Prompts use model-discretion wording (search when you choose — not forced every turn). See agents/ for per-agent templates.

Native web search: With --replace-native (default when non-interactive), Codex gets a marked top-level web_search = "disabled" in config.toml (never inside [mcp_servers.*]); Claude gets an ownership-marked WebSearch deny in settings.json. Uninstall removes only search-boost-owned entries and restores native search when safe. Cursor / Antigravity rely on skill + hook preference only. Grok native browse is left on.

Cursor + Cursor CLI: Both targets share one ~/.cursor/ surface. Installing -t cursor,cursor-cli merges IDE + CLI prompts into a single write; uninstall clears the shared surface.

Antigravity + agy CLI: On the api layer, the optional Antigravity CLI engine (agy on PATH) joins medium and complex fused_search tiers only — not simple lookups. It depends on local sign-in and platform quota; timeouts are ~45s.

Grok Build: search-boost install -t grok -y --auto-allow runs grok plugin install <bundled grok-plugin> --trust when the Grok CLI is on PATH, then writes config.toml, rule, and skill. If grok is not on PATH, the plugin step is skipped with a warning and the config install still proceeds. Use --skip-grok-plugin for config/rule/skill only. Re-install is idempotent for [permission] blocks (marked or legacy); uninstall strips search-boost-owned permission lines. If [ui] permission_mode = "always-approve", --auto-allow skips injecting [permission]. The plugin's .mcp.json uses portable npx; config.toml uses resolveMcpLaunch() (local node when developing from a clone) — both can coexist. Manual plugin install: grok plugin install ./grok-plugin --trust (advanced) → grok-plugin/README.md.

Troubleshooting

Symptom	What to try
Is search-boost healthy?	`search-boost doctor` — pass/warn/fail verdict; `--json` for scripts
Install fails immediately	Node ≥ 22.13 (`node -v`); upgrade if older
MCP server missing in agent	Re-run install, restart the agent, check `search-boost status`
Tool calls blocked / approval every turn	Re-install with `--auto-allow`, or approve once in the agent UI
No results / empty engines	`search-boost doctor` — check layer/keys/engine checks; free needs no keys; api needs at least one keyed engine via `search-boost config keys` or env vars (all three recommended)
Network/proxy issues	Phase 2: `search-boost doctor --probe` (not yet implemented)
MCP won't start	`search-boost doctor` → `mcp_launch_command`, `node_version`; then `search-boost serve`
Grok plugin MCP won't start	`grok mcp doctor search-boost`; ensure `npx` and network access work
`grok` fails on config.toml parse	Duplicate `[permission]` — run `search-boost install -t grok -y --auto-allow`
Antigravity `agy` never runs	Requires api layer, `agy` on PATH, and `complexity` medium/complex — not simple
Timeouts / fetch errors	Corporate proxy or firewall may block Bing/DDG/Jina; try `search-boost serve` locally to read stderr

Development

git clone https://github.com/Mr-remon219/search-boost.git
cd search-boost && npm install
npm run check && npm run test:install && npm run smoke
node cli.mjs install --dry-run -y

Local clone installs write node /path/to/cli.mjs serve (not npx). No sibling checkout or SEARCH_BOOST_DSH_ROOT is required.

License

MIT

Links: Issues · dsh-search-boost · pi-search-boost

Friendly link: LINUX DO 社区

Project	For	Link
search-boost (this repo)	Cursor · Codex · Claude · Grok · Antigravity via MCP	you are here
dsh-search-boost	DeepSeek Harness bundle plugin	GitHub · npm
pi-search-boost	pi extension	GitHub · npm