GrokSearch-rs

A lightweight Rust MCP server for Grok / OpenAI‑compatible web search, backed by an ordered source chain — Tavily, Exa, TinyFish, Firecrawl — for supplemental sources, fetch, and map.

grok-search-rs is an MCP server — run it locally over stdio (your client launches it; you do not run it directly) or as a remote Streamable HTTP service for mobile / multi‑device access (see self-hosting). It exposes one set of tools (web_search, get_sources, web_fetch, web_map, doctor) and supports two upstream transports so you can plug into either xAI's official API or any OpenAI‑compatible relay.

Features

• 🔎 Live web search with cited sources, cached for follow‑up get_sources calls. Opt‑in include_content enriches the top sources with full extracted text in one call.
• 📏 Response budgeting — web_search keeps responses inside agent context limits: only the top max_inline_sources carry inline text, a whole‑response char budget (response_max_chars, default 45k — sized to stay under the MCP client token ceiling after JSON serialization) trims tail sources with recovery notes, response_format: "concise" | "detailed" picks the payload size, and get_sources pages through cached sources with offset/limit. The session cache always keeps full content.
• 🧩 Structured web_fetch — GitHub issues/PRs/releases, StackExchange/MathOverflow, arXiv, and Wikipedia URLs are parsed by specialist extractors into clean Markdown (title, state/labels, release notes, accepted‑answer ordering, abstracts, vote‑sorted answers). Specialist extractors need no API key. Anything else falls back to the generic source chain (Tavily → Exa → TinyFish → Firecrawl, as configured) — so with no source provider configured, ordinary URLs cannot be fetched at all, only the specialist families above. Output carries source_type and a fallback_reason when a specialist was skipped.
• 🔀 Two transports — native xAI Responses (/v1/responses) or any OpenAI‑compatible chat‑completions gateway (/v1/chat/completions). Pick by env vars; no flag.
• 🔐 Optional Grok OAuth mode — login/status/logout commands store a local xAI OAuth token for Responses auth, so the MCP server can run without GROK_SEARCH_API_KEY.
• 🌐 Optional remote mode — build with --features http to serve the same tools over Streamable HTTP (multi‑tenant, bring‑your‑own‑key via request headers) for mobile / multi‑device access. See self-hosting.
• 📥 Pluggable source chain — supplemental sources and generic fetch walk an ordered provider chain: Tavily (RAG‑tuned search + extract + map), Exa (semantic search, native domain/date filters), TinyFish (free search + JS‑rendering fetch), Firecrawl (robust scrape fallback). First provider with results wins; GROK_SEARCH_SOURCE_PROVIDERS reorders. TAVILY_API_KEY accepts a comma‑separated key list — keys rotate round‑robin with automatic failover on rate/quota errors.
• 🐦 Optional X/Twitter search via x_search (Responses transport only).
• 🚦 Concurrent stdio requests — up to 8 tool calls are handled at once; anything beyond that queues rather than being refused. Responses come back in completion order, paired to requests by JSON‑RPC id.
• 🩺 doctor — connectivity probe + redacted config in one tool call, including whether your config file was found, loaded, or rejected (and why).
• 🗂 Single global config file so multiple MCP clients share one set of keys.

Install

bashCopy code
npm install -g grok-search-rs

The npm package ships a native Rust binary; the grok-search-rs command is what your MCP client launches.

Quick Start

Option A — use the hosted instance (no install). Point any MCP client that supports remote HTTP + custom headers at the public endpoint and pass your own keys as headers:

bashCopy code
claude mcp add --transport http grok-search https://mcp.episkeyai.com/groksearch_rs/mcp \
  --header "X-Grok-Api-Key: xai-..." \
  --header "X-Tavily-Api-Key: tvly-..."

The default gateway is xAI official (api.x.ai) — use an xAI key. For any other Grok‑compatible gateway, add --header "X-Grok-Base-Url: https://your-gateway.example/v1" with a matching key, and optionally --header "X-Grok-Model: <model>" (model ids are gateway‑specific). No keys are stored server-side; best-effort availability. Prefer your own server? See self-hosting.

Option B — install locally (stdio).

1. After npm install -g grok-search-rs, add this MCP server entry to your client config:

   jsonCopy code
   {
     "grok-search-rs": {
       "command": "grok-search-rs",
       "args": [],
       "env": {
         "GROK_SEARCH_API_KEY": "",
         "GROK_SEARCH_URL": "",
         "GROK_SEARCH_MODEL": "grok-4.20-fast",
         "TAVILY_API_KEY": "",
         "TAVILY_API_URL": "https://api.tavily.com",
         "FIRECRAWL_API_KEY": ""
       }
     }
   }
   

   For Codex TOML config:

   tomlCopy code
   [mcp_servers.grok-search-rs]
   type = "stdio"
   command = "grok-search-rs"
   
   [mcp_servers.grok-search-rs.env]
   FIRECRAWL_API_KEY = ""
   GROK_SEARCH_API_KEY = ""
   GROK_SEARCH_MODEL = "grok-4.20-fast"
   GROK_SEARCH_URL = ""
   TAVILY_API_KEY = ""
   TAVILY_API_URL = "https://api.tavily.com"
   

   Put your real keys in the empty values. If your client expects a top-level mcpServers / mcp_servers object, place the grok-search-rs entry under that section.

2. Optional: scaffold a shared global config file instead of duplicating env blocks in every MCP client:

   bashCopy code
   grok-search-rs --init
   $EDITOR ~/.config/grok-search-rs/config.toml
   

3. Verify:

   textCopy code
   Ask your assistant: "call doctor"
   

   Successful output shows reachable: true for each enabled upstream and transport: Responses (or ChatCompletions).

Configuration

The MCP transport decides how config reaches the server — same values, different channel (forced by the transport, not a project setting):

• stdio (local): environment variables — the env block in your MCP client config.
• remote HTTP: per-request HTTP headers — the server stores no keys.

The tables below use env-key names (they also drive config.toml / stdio); on the remote transport send the header from the row above. Full reference and per-transport examples: docs/CONFIGURATION.md. All source-provider keys (Tavily / Exa / TinyFish / Firecrawl) are shared across transports.

A. Native Grok Responses (default)

Verified upstream: xAI (https://api.x.ai, both tools). Other Grok‑compatible gateways work with a matching key; x_search availability depends on the gateway.

OAuth mode is a single-binary flow:

bashCopy code
grok-search-rs login
grok-search-rs status
grok-search-rs logout

Then configure your MCP client with:

tomlCopy code
[mcp_servers.grok-search-rs]
command = "grok-search-rs"

[mcp_servers.grok-search-rs.env]
GROK_SEARCH_AUTH_MODE = "oauth"
GROK_SEARCH_MODEL = "grok-4.3"
GROK_SEARCH_WEB_SEARCH = "true"

OAuth mode reuses Hermes' xAI OAuth client id and stores auth.json locally. That may violate xAI terms or affect your account; do not share the token file. If xAI changes or blocks that OAuth flow, switch back to api_key mode.

B. OpenAI‑compatible chat/completions

Activate by setting the URL and key while leaving GROK_SEARCH_API_KEY unset. Suitable for any OpenAI‑compatible relay (one‑api, vLLM, LiteLLM, marybrown, Perplexity‑style gateways, etc.).

Notes:

• GROK_SEARCH_WEB_SEARCH=true (default) appends tools:[{"type":"web_search"}] to the payload. Relays that auto‑search server‑side simply ignore it.
• GROK_SEARCH_X_SEARCH=true is silently ignored on this transport (a one‑line stderr warning prints at startup). x_search only exists on the Responses API.
• Source extraction reads four parallel paths and de‑duplicates by URL: OpenAI annotations[].url_citation, Perplexity‑style citations, top‑level search_sources[], and inline [[n]](url) markers.

Source providers (shared)

Source extraction (web_fetch specialists / web_search enrichment)

These specialists need no Tavily/Firecrawl key — they hit the public GitHub, StackExchange, arXiv, and Wikipedia APIs directly. Tavily/Firecrawl are only used for the generic fallback path.

Selection rules at startup

1. If GROK_SEARCH_AUTH_MODE=oauth → Responses transport with the local OAuth token.
2. Else if GROK_SEARCH_API_KEY is set → Responses transport with a static Bearer key.
3. Else if both OPENAI_COMPATIBLE_API_URL and OPENAI_COMPATIBLE_API_KEY are set → ChatCompletions transport.
4. Else → server fails with a clear MissingConfig error.

Global config file

Tired of duplicating env blocks across clients? Run grok-search-rs --init once to scaffold <home>/.config/grok-search-rs/config.toml, fill in your keys, and every client can shrink to {"command": "grok-search-rs"}.

Precedence: per‑client env > config file > built‑in defaults. File keys are lowercase snake_case (env GROK_SEARCH_MODEL → file grok_model). Unknown keys are rejected. Full reference: docs/CONFIGURATION.md.

MCP Tools

Self-hosting (remote HTTP)

Besides the default stdio mode, grok-search-rs can run as a remote, multi‑tenant Streamable HTTP MCP server so mobile / on‑the‑go / multi‑device clients can reach it over the network. It is opt‑in behind the http Cargo feature — the default build is unchanged (pure stdio, no HTTP dependencies linked in).

Bring‑your‑own‑key, zero shared credentials. The server stores no API keys. Each request carries the caller's own keys as headers, so many users can share one endpoint and each pays with their own keys:

• X-Grok-Api-Key, X-Tavily-Api-Key, X-Firecrawl-Api-Key (optional X-GitHub-Token)
• Optional non‑secret overrides: X-Grok-Base-Url (gateway), X-Grok-Model (model name, since model ids are gateway‑specific)

This cuts both ways: setting TAVILY_API_KEY / FIRECRAWL_API_KEY in the server's own environment (compose file, .env, systemd unit) has no effect — those are stripped from every per‑request config, so requests that don't carry the header run with no source fallback at all. The server logs a warning at startup for each such variable it finds.

A missing required key returns 401 (fail‑closed); OAuth is rejected on this transport (stdio only). The operator sets the default Grok‑compatible gateway via GROK_SEARCH_URL (default https://api.x.ai), and callers may point at any other Grok‑compatible gateway with an X-Grok-Base-Url header (any public gateway is honored; internal/private addresses are rejected). The remote transport uses the Grok Responses API only; the OpenAI-compatible chat-completions transport is stdio-only.

No local build needed. Every release ships ready‑to‑run server artifacts for Linux x86_64 + aarch64 (static musl) — ideal for low‑RAM/small‑disk boards where a native cargo build would OOM or fill the disk:

• Prebuilt binary — download grok-search-rs-http_Linux_<arch>.tar.gz from the latest release and run GROK_MCP_BIND=0.0.0.0:8080 ./grok-search-rs --http. (The plain grok-search-rs_… assets are stdio‑only: the HTTP transport is compile‑time gated and not in them.)
• Docker image — multi‑arch amd64/arm64: docker pull ghcr.io/episkey-g/grok-search-rs:latest (serves on :8080).

Building from source instead:

bashCopy code
cargo build --profile release-http --features http    # release-http => panic=unwind (handler panic won't kill the server)
GROK_MCP_BIND=127.0.0.1:8080 target/release-http/grok-search-rs --http   # bind loopback; terminate TLS upstream

Put a TLS‑terminating reverse proxy (e.g. Caddy) in front. The repo ships a Dockerfile, Dockerfile.deploy (runtime‑only, multi‑arch amd64/arm64 — cross‑compile the binaries first with scripts/build-deploy-dist.sh; ideal for low‑RAM hosts), docker-compose.yml, and Caddyfile for a one‑command deploy with automatic HTTPS. Set MCP_HOSTNAME (your domain or a <dashed-ip>.sslip.io name) via the environment or a git‑ignored .env — not in the repo.

Connect a client the same way as the hosted instance (Quick Start), pointing url at your own host (https://<your-host>/groksearch_rs/mcp).

Rotating a key

Keys are never stored server‑side, so rotation is entirely client‑side:

• stdio — update the key in your MCP client's env block (or the global config.toml) and restart the client.
• remote HTTP — update the header value in your client config. For Claude Code:

  bashCopy code
  claude mcp remove grok-search -s user
  claude mcp add --transport http grok-search https://<your-host>/groksearch_rs/mcp \
    --header "X-Grok-Api-Key: <new-key>" --header "X-Tavily-Api-Key: <new-key>"
  

Rotate immediately if a key was ever printed, logged, or shared.

Build from source

bashCopy code
git clone https://github.com/Episkey-G/GrokSearch-rs.git
cd GrokSearch-rs
cargo build --release

The binary lands at target/release/grok-search-rs. Point your MCP client's command at the absolute path.

Development

bashCopy code
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

More docs:

• Configuration
• Architecture
• Testing

⭐ Star History

Acknowledgements

• Inspired by GuDaStudio/GrokSearch — the original Python implementation that pioneered the Grok + Tavily + Firecrawl combo this project rewrites in Rust.
• Thanks to the LinuxDo community for the discussions, feedback, and the prior art that inspired this rewrite.

License

MIT — see LICENSE.