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.
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador

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.
Rust MCP server for Grok web search and Tavily-backed source retrieval
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.
get_sources calls. Opt‑in include_content enriches the top sources with full extracted text in one call.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.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./v1/responses) or any OpenAI‑compatible chat‑completions gateway (/v1/chat/completions). Pick by env vars; no flag.login/status/logout commands store a local xAI OAuth token for Responses auth, so the MCP server can run without GROK_SEARCH_API_KEY.--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.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.x_search (Responses transport only).id.doctor — connectivity probe + redacted config in one tool call, including whether your config file was found, loaded, or rejected (and why).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.
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:
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).
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.
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
Verify:
Ask your assistant: "call doctor"
Successful output shows reachable: true for each enabled upstream and transport: Responses (or ChatCompletions).
The MCP transport decides how config reaches the server — same values, different channel (forced by the transport, not a project setting):
env block in your MCP client config.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.
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:
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.annotations[].url_citation, Perplexity‑style citations, top‑level search_sources[], and inline [[n]](url) markers.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.
GROK_SEARCH_AUTH_MODE=oauth → Responses transport with the local OAuth token.GROK_SEARCH_API_KEY is set → Responses transport with a static Bearer key.OPENAI_COMPATIBLE_API_URL and OPENAI_COMPATIBLE_API_KEY are set → ChatCompletions transport.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.
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)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:
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.)amd64/arm64:
docker pull ghcr.io/episkey-g/grok-search-rs:latest (serves on :8080).Building from source instead:
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).
Keys are never stored server‑side, so rotation is entirely client‑side:
env block (or the global config.toml)
and restart the client.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.
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:
MIT — see LICENSE.
Rust MCP server for Grok web search and Tavily-backed source retrieval
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
GrokSearch Rs se ejecuta localmente por stdio.
Última comprobación: 2026-10-27. Rust MCP server for Grok web search and Tavily-backed source retrieval