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 社区