GrokSearch

# Grok Search MCP [中文](./README.md) | [English](./docs/README_EN.md) `grok-search` is a search-oriented MCP server based on FastMCP, designed for coding agents like OpenCode and Claude Code, providing more stable internet search, web scraping, site mapping, source caching, and search planning capabilities. ## Features - Official xAI priority with third-party Grok compatible interface automatic fallback - Supports `web_search`, `web_fetch`, `web_map`, `get_sources` - Supports Tavily scraping and site mapping - Supports Firecrawl as a fallback for scraping failures - Supports OpenCode / Claude Code integration - Supports multi-stage search planning tool chain - Automatically cleans `<think>...</think>` to avoid directly transmitting thought content to clients ## grok2api Compatibility - Compatible with `grok2api` deployment methods that provide OpenAI compatible interfaces - Expects at least `/models` and `/chat/completions` - Recommended mode: - Official xAI as the main route - `grok2api` as fallback Example: ```env OFFICIAL_GROK_API_URL=https://api.x.ai/v1 OFFICIAL_GROK_API_KEY=your-xai-api-key OFFICIAL_GROK_MODEL=grok-4.20-multi-agent-0309 GROK_API_URL=https://your-grok2api-endpoint/v1 GROK_API_KEY=your-grok2api-key GROK_MODEL=grok-4.20-beta ``` ## Applicable Scenarios This project is not just about wrapping the Grok API with an MCP layer. It's more about providing a complete search infrastructure for coding agents, suitable for scenarios such as: - Needing to search, then scrape webpage content, and extract sources - Needing to perform search planning for complex questions - Needing stable access to Grok search capabilities in OpenCode / Claude Code - Needing both official xAI and third-party compatible interface dual routing ## Tool List ### Search and Scraping - `web_search` - `get_sources` - `web_fetch` - `web_map` ### Configuration and Models - `get_config_info` - `switch_model` ### Search Planning - `plan_intent` - `plan_complexity` - `plan_sub_query` - `plan_search_term` - `plan_tool_mapping` - `plan_execution` ### Optional Auxiliary Tools - `toggle_builtin_tools` This tool is primarily for Claude Code; OpenCode does not depend on it. ## Installation ### 1. Create Environment ```bash python -m venv .venv source .venv/bin/activate ``` Windows PowerShell: ```powershell python -m venv .venv-win .\.venv-win\Scripts\Activate.ps1 ``` ### 2. Install Dependencies ```bash pip install -e . ``` ### 3. Configure Environment Variables Copy `.env.example` to `.env.local` or directly inject into the runtime environment. Minimum official configuration: ```env OFFICIAL_GROK_API_KEY=your-xai-api-key OFFICIAL_GROK_MODEL=grok-4.20-multi-agent-0309 ``` If a third-party fallback is also needed: ```env GROK_API_URL=https://your-fallback-endpoint.example/v1 GROK_API_KEY=your-fallback-api-key GROK_MODEL=grok-4.20-beta ``` If the fallback is `grok2api`, point `GROK_API_URL` to its OpenAI compatible entry. ## Running ### Run Directly as stdio MCP ```bash grok-search ``` ### Run via Local HTTP / SSE Gateway Windows: ```powershell powershell -ExecutionPolicy Bypass -File .\start-local.ps1 ``` Hidden startup: ```text Double-click start-local-hidden.vbs ``` ## OpenCode Integration Example `opencode.jsonc` example: ```json { "mcp": { "grok-search": { "type": "local", "command": ["C:\\path\\to\\grok-search.exe"], "enabled": true, "environment": { "OFFICIAL_GROK_API_KEY": "your-xai-api-key", "OFFICIAL_GROK_MODEL": "grok-4.20-multi-agent-0309", "GROK_API_URL": "https://your-fallback-endpoint.example/v1", "GROK_API_KEY": "your-fallback-api-key" } } } } ``` ## Documentation - [English Documentation](./docs/README_EN.md) - [Deployment Documentation](./docs/DEPLOYMENT.md) - [Open Source Description](./docs/OPEN_SOURCE.md) - [GitHub Project Introduction](./docs/GITHUB_REPO_PROFILE.md) ## Security Notes - Do not submit `.env.local` - Do not submit logs and virtual environments - Do not write real API Keys into public scripts - Recommended to prioritize official xAI, with third-party compatible interfaces as fallback ## License This project uses the [MIT License](./LICENSE)