[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77092":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":29,"discoverSource":30},77092,"GrokSearch-rs","Episkey-G\u002FGrokSearch-rs","Episkey-G","Rust MCP server for Grok web search and Tavily-backed source retrieval",null,"Rust",191,19,8,1,0,2,11,148,14,3.9,"MIT License",false,"main",true,[],"2026-06-12 02:03:42","# GrokSearch-rs\n\n![GrokSearch-rs product banner](assets\u002Fgroksearch-rs-banner.png)\n\n**A lightweight Rust MCP server for Grok \u002F OpenAI‑compatible web search, plus Tavily fetch\u002Fmap and Firecrawl fallback.**\n\n`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.\n\n---\n\n## Features\n\n- 🔎 **Live web search** with cited sources, cached for follow‑up `get_sources` calls.\n- 🔀 **Two transports** — native xAI Responses (`\u002Fv1\u002Fresponses`) **or** any OpenAI‑compatible chat‑completions gateway (`\u002Fv1\u002Fchat\u002Fcompletions`). Pick by env vars; no flag.\n- 🔐 **Optional Grok OAuth mode** — `login\u002Fstatus\u002Flogout` commands store a local xAI OAuth token for Responses auth, so the MCP server can run without `GROK_SEARCH_API_KEY`.\n- 📥 **Tavily fetch \u002F map** for full‑text extraction and link discovery, with **Firecrawl** as automatic fallback.\n- 🐦 **Optional X\u002FTwitter search** via `x_search` (Responses transport only).\n- 🩺 **`doctor`** — connectivity probe + redacted config in one tool call.\n- 🗂 **Single global config file** so multiple MCP clients share one set of keys.\n\n---\n\n## Install\n\n```bash\nnpm install -g grok-search-rs\n```\n\nThe npm package ships a native Rust binary; the `grok-search-rs` command is what your MCP client launches.\n\n---\n\n## Quick Start\n\n1. Scaffold a global config file (one‑time, optional):\n\n   ```bash\n   grok-search-rs --init\n   $EDITOR ~\u002F.config\u002Fgrok-search-rs\u002Fconfig.toml\n   ```\n\n2. Wire it into one MCP client. Example for Claude Code:\n\n   ```bash\n   claude mcp add-json grok-search-rs --scope user '{\n     \"type\": \"stdio\",\n     \"command\": \"grok-search-rs\",\n     \"env\": {\n       \"GROK_SEARCH_API_KEY\": \"xai-...\",\n       \"TAVILY_API_KEY\": \"tvly-...\"\n     }\n   }'\n   ```\n\n   For other clients (Codex \u002F Cursor \u002F Gemini \u002F VS Code \u002F Windsurf), use the same JSON shape inside their MCP config file. If you ran `--init` and put your keys in the config file, the `env` block can be omitted.\n\n3. Verify:\n\n   ```text\n   Ask your assistant: \"call doctor\"\n   ```\n\n   Successful output shows `reachable: true` for each enabled upstream and `transport: Responses` (or `ChatCompletions`).\n\n---\n\n## Configuration\n\nPick **one** transport group. Both Tavily and Firecrawl keys are shared across transports.\n\n### A. Native Grok Responses (default)\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GROK_SEARCH_AUTH_MODE` | `api_key` | `api_key` uses `GROK_SEARCH_API_KEY`; `oauth` uses the local token from `grok-search-rs login`. |\n| `GROK_SEARCH_API_KEY` | — *(required in `api_key` mode)* | Bearer token for the Grok \u002F xAI gateway. |\n| `GROK_SEARCH_AUTH_FILE` | `\u003Chome>\u002F.config\u002Fgrok-search-rs\u002Fauth.json` | Optional OAuth token file override. |\n| `GROK_SEARCH_URL` | `https:\u002F\u002Fapi.x.ai` | Root, `\u002Fv1`, or full‑endpoint URL. |\n| `GROK_SEARCH_MODEL` | `grok-4-1-fast-reasoning` | Model name. |\n| `GROK_SEARCH_WEB_SEARCH` | `true` | Offer `web_search` tool to Grok. |\n| `GROK_SEARCH_X_SEARCH` | `false` | Offer `x_search` tool (X\u002FTwitter) to Grok. |\n\nVerified upstreams: **xAI** (`https:\u002F\u002Fapi.x.ai`, both tools), **Modelverse** (`https:\u002F\u002Fapi.modelverse.cn`, `x_search` depends on relay).\n\nOAuth mode is a single-binary flow:\n\n```bash\ngrok-search-rs login\ngrok-search-rs status\ngrok-search-rs logout\n```\n\nThen configure your MCP client with:\n\n```toml\n[mcp_servers.grok-search-rs]\ncommand = \"grok-search-rs\"\n\n[mcp_servers.grok-search-rs.env]\nGROK_SEARCH_AUTH_MODE = \"oauth\"\nGROK_SEARCH_MODEL = \"grok-4.3\"\nGROK_SEARCH_WEB_SEARCH = \"true\"\n```\n\nOAuth 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.\n\n### B. OpenAI‑compatible chat\u002Fcompletions\n\nActivate 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.).\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `OPENAI_COMPATIBLE_API_URL` | — | Root, `\u002Fv1`, or full‑endpoint URL. |\n| `OPENAI_COMPATIBLE_API_KEY` | — | Bearer token for the relay. |\n| `OPENAI_COMPATIBLE_MODEL` | falls back to `GROK_SEARCH_MODEL` | Model name to send. |\n\nNotes:\n\n- `GROK_SEARCH_WEB_SEARCH=true` (default) appends `tools:[{\"type\":\"web_search\"}]` to the payload. Relays that auto‑search server‑side simply ignore it.\n- `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.\n- 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.\n\n### Tavily \u002F Firecrawl (shared)\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `TAVILY_API_KEY` | — *(required for `web_fetch` \u002F `web_map`)* | Tavily key. |\n| `TAVILY_API_URL` | `https:\u002F\u002Fapi.tavily.com` | Tavily base. |\n| `GROK_SEARCH_EXTRA_SOURCES` | `3` | Extra Tavily sources after a Grok answer (`0` disables). |\n| `GROK_SEARCH_FALLBACK_SOURCES` | `5` | Fallback source count when the AI step can't verify itself. |\n| `FIRECRAWL_API_KEY` | unset | Enables Firecrawl as `web_fetch` \u002F source fallback. |\n| `FIRECRAWL_API_URL` | `https:\u002F\u002Fapi.firecrawl.dev` | Firecrawl base. |\n| `GROK_SEARCH_CACHE_SIZE` | `256` | Max cached `web_search` sessions. |\n| `GROK_SEARCH_TIMEOUT_SECONDS` | `60` | HTTP timeout for all upstreams. |\n| `GROK_SEARCH_FETCH_MAX_CHARS` | unset | Default char cap on `web_fetch`. |\n\n### Selection rules at startup\n\n1. If `GROK_SEARCH_AUTH_MODE=oauth` → **Responses** transport with the local OAuth token.\n2. Else if `GROK_SEARCH_API_KEY` is set → **Responses** transport with a static Bearer key.\n3. Else if both `OPENAI_COMPATIBLE_API_URL` and `OPENAI_COMPATIBLE_API_KEY` are set → **ChatCompletions** transport.\n4. Else → server fails with a clear `MissingConfig` error.\n\n### Global config file\n\nTired of duplicating `env` blocks across clients? Run `grok-search-rs --init` once to scaffold `\u003Chome>\u002F.config\u002Fgrok-search-rs\u002Fconfig.toml`, fill in your keys, and every client can shrink to `{\"command\": \"grok-search-rs\"}`.\n\n| Path order | Location |\n|---|---|\n| 1 | `$GROK_SEARCH_CONFIG` (explicit override, any platform) |\n| 2 | `$HOME\u002F.config\u002Fgrok-search-rs\u002Fconfig.toml` (Unix \u002F macOS \u002F Git Bash) |\n| 3 | `%USERPROFILE%\\.config\\grok-search-rs\\config.toml` (native Windows) |\n\n**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\u002FCONFIGURATION.md](docs\u002FCONFIGURATION.md).\n\n---\n\n## MCP Tools\n\n| Tool | When to call it |\n|---|---|\n| `web_search` | Sourced summary for a topic. Sources cached for follow‑up. |\n| `get_sources` | Re‑fetch sources of a previous `web_search` by `session_id`. |\n| `web_fetch` | Page content (Tavily → Firecrawl fallback). |\n| `web_map` | Discover URLs on a domain via Tavily Map. |\n| `doctor` | Live connectivity probe + redacted config. Run first when something looks off. |\n\n---\n\n## Build from source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FEpiskey-G\u002FGrokSearch-rs.git\ncd GrokSearch-rs\ncargo build --release\n```\n\nThe binary lands at `target\u002Frelease\u002Fgrok-search-rs`. Point your MCP client's `command` at the absolute path.\n\n---\n\n## Development\n\n```bash\ncargo fmt --check\ncargo clippy --all-targets -- -D warnings\ncargo test\n```\n\nMore docs:\n\n- [Configuration](docs\u002FCONFIGURATION.md)\n- [Architecture](docs\u002FARCHITECTURE.md)\n- [Testing](docs\u002FTESTING.md)\n\n---\n\n## ⭐ Star History\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=Episkey-G%2FGrokSearch-rs&type=Date\">\n  \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=Episkey-G\u002FGrokSearch-rs&type=Date\" \u002F>\n\u003C\u002Fa>\n\n---\n\n## Acknowledgements\n\n- Inspired by [GuDaStudio\u002FGrokSearch](https:\u002F\u002Fgithub.com\u002FGuDaStudio\u002FGrokSearch) — the original Python implementation that pioneered the Grok + Tavily + Firecrawl combo this project rewrites in Rust.\n- Thanks to the [LinuxDo](https:\u002F\u002Flinux.do) community for the discussions, feedback, and the prior art that inspired this rewrite.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","GrokSearch-rs 是一个轻量级的 Rust MCP 服务器，用于 Grok\u002FOpenAI 兼容的网页搜索和 Tavily 支持的源检索。其核心功能包括实时网页搜索并引用来源、支持两种传输方式（原生 xAI 响应或任何 OpenAI 兼容的聊天完成网关）、可选的 Grok OAuth 模式以存储本地 xAI OAuth 令牌进行身份验证、Tavily 全文提取和链接发现以及 Firecrawl 自动回退机制。此外，它还提供了一个全局配置文件，方便多个 MCP 客户端共享一套密钥。该项目适用于需要集成高级搜索功能的开发者工具场景，如代码编辑器插件、自动化脚本等。","2026-06-11 03:55:05","CREATED_QUERY"]