A lightweight Rust MCP server for Grok / OpenAI‑compatible web search, plus Tavily fetch/map and Firecrawl fallback.

grok-search-rs is an MCP stdio server — your client (Claude Code, Codex, Cursor, VS Code, …) launches it; you do not run it directly. 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.

• 🔎 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.
• 🧩 Structured web_fetch — GitHub issues/PRs, StackExchange/MathOverflow, arXiv, and Wikipedia URLs are parsed by specialist extractors into clean Markdown (title, state/labels, accepted‑answer ordering, abstracts, vote‑sorted answers). Anything else falls back to the generic Tavily → Firecrawl chain. 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.
• 📥 Tavily fetch / map for full‑text extraction and link discovery, with Firecrawl as automatic fallback.
• 🐦 Optional X/Twitter search via x_search (Responses transport only).
• 🩺 doctor — connectivity probe + redacted config in one tool call.
• 🗂 Single global config file so multiple MCP clients share one set of keys.

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.

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

   {
     "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:

   [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:

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

3. Verify:

   Ask your assistant: "call doctor"
   

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

Pick one transport group. Both Tavily and Firecrawl keys are shared across transports.

Verified upstreams: xAI (https://api.x.ai, both tools), Modelverse (https://api.modelverse.cn, x_search depends on relay).

OAuth mode is a single-binary flow:

grok-search-rs login
grok-search-rs status
grok-search-rs logout

Then configure your MCP client with:

[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.

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.

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.

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.

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.

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.

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

More docs:

• Configuration
• Architecture
• Testing

• 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.

MIT — see LICENSE.