GrokSearch

<div align="center"> <img src="./images/title.png"> [English](./docs/README_EN.md) | 简体中文 **Integrate Grok search capability into Claude via MCP protocol to significantly enhance document retrieval and fact-checking capabilities** [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/jlowin/fastmcp) </div> --- ## Overview Grok Search MCP is an MCP (Model Context Protocol) server built on [FastMCP](https://github.com/jlowin/fastmcp), providing real-time web search capabilities for AI models such as Claude and Claude Code by relaying the powerful search capabilities of third-party platforms (such as Grok). ### Core Value - **Break through knowledge cutoff limitations**: Allow Claude to access the latest network information, no longer limited by training data time. - **Enhance fact-checking**: Real-time search to verify the accuracy and timeliness of information. - **Structured output**: Returns standardized JSON containing titles, links, and summaries, making it easy for AI models to understand and cite. - **Plug and play**: Seamlessly integrated into clients such as Claude Desktop and Claude Code via the MCP protocol. **Workflow**: `Claude → MCP → Grok API → Search/Crawl → Structured Return` <details> <summary><b>💡 More reasons to choose Grok search</b></summary> Comparison with other search solutions: | Feature | Grok Search MCP | Google Custom Search API | Bing Search API | SerpAPI | |------|----------------|-------------------------|-----------------|---------| | **AI Optimized Results** | ✅ Optimized for AI understanding | ❌ General search results | ❌ General search results | ❌ General search results | | **Content Summary Quality** | ✅ AI generates high-quality summaries | ⚠️ Need secondary processing | ⚠️ Need secondary processing | ⚠️ Need secondary processing | | **Real-time** | ✅ Real-time network data | ✅ Real-time | ✅ Real-time | ✅ Real-time | | **Integration Complexity** | ✅ MCP plug and play | ⚠️ Need to develop by yourself | ⚠️ Need to develop by yourself | ⚠️ Need to develop by yourself | | **Return Format** | ✅ AI friendly JSON | ⚠️ Need to format | ⚠️ Need to format | ⚠️ Need to format | ## Features - ✅ OpenAI compatible interface, environment variable configuration - ✅ Real-time web search + web content crawling - ✅ Support specifying search platforms (Twitter, Reddit, GitHub, etc.) - ✅ Configuration testing tools (connection test + API Key desensitization) - ✅ Dynamic model switching (supports switching between different Grok models and persistent saving) - ✅ **Tool routing control (one-click disable official WebSearch/WebFetch, force use of GrokSearch)** - ✅ **Automatic time injection (automatically obtain local time during search to ensure the accuracy of time-related queries)** - ✅ Extensible architecture, supports adding other search Providers </details> ## Installation tutorial ### Step 0. Preparation (skip this step if uv has already been installed) <details> **Python Environment**: - Python 3.10 or higher - Claude Code or Claude Desktop has been configured **uv tool** (recommended Python package manager): Please ensure that you have successfully installed the [uv tool](https://docs.astral.sh/uv/getting-started/installation/): #### Install uv on Windows Run the following command in PowerShell: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **💡 Important Note**: We **strongly recommend** Windows users run this project in WSL (Windows Subsystem for Linux)! #### Install uv on Linux/macOS Download and install using curl or wget: ```bash # Use curl curl -LsSf https://astral.sh/uv/install.sh | sh # Or use wget wget -qO- https://astral.sh/uv/install.sh | sh ``` </details> ### Step 1. Install Grok Search MCP Use `claude mcp add-json` to install and configure with one click: **Note:** You need to replace the **GROK_API_URL** and **GROK_API_KEY** fields with your own site and key. Currently, only openai format is supported, so if you need to use grok, you also need to use a grok mirror site converted to openai format. ```bash claude mcp add-json grok-search --scope user '{ "type": "stdio", "command": "uvx", "args": [ "--from", "git+https://github.com/GuDaStudio/GrokSearch", "grok-search" ], "env": { "GROK_API_URL": "https://your-api-endpoint.com/v1", "GROK_API_KEY": "your-api-key-here" } }' ``` ### Step 2. Verify installation & check MCP configuration ```bash claude mcp list ``` You should be able to see that the `grok-search` server has been registered. After the configuration is complete, it is **strongly recommended** to run a configuration test in Claude dialogue to ensure everything is normal: Enter in Claude dialogue: ``` Please test the configuration of Grok Search ``` Or say directly: ``` Show grok-search configuration information ``` The tool will automatically perform the following checks: - ✅ Verify that environment variables are loaded correctly - ✅ Test API connection (send request to `/models` endpoint) - ✅ Display response time and number of available models - ✅ Identify and report any configuration errors If you see `❌ Connection failed` or `⚠️ Connection exception`, please check: - Whether the API URL is correct - Whether the API Key is valid - Whether the network connection is normal ### Step 3. Configure system prompt In order to better use Grok Search, you can optimize the overall Vibe Coding Cli by configuring Claude Code or similar system prompts. Taking Claude Code as an example, you can add the following content to ~/.claude/CLAUDE.md. Two versions are provided, and the detailed version can better activate the tool's capabilities: **💡 Tip**: You can now use the `toggle_builtin_tools` tool to disable the official WebSearch/WebFetch with one click and force routing to GrokSearch! #### Concise version prompt ```markdown # Grok Search prompt Concise version ## Activation and routing **Trigger**: Automatically activate when network search/web page crawling/latest information query **Replace**: Use Grok-search tools as much as possible to replace the official native search and fetch functions ## Tool Matrix | Tool | Parameters | Output | Use Case | |------|------------|--------|----------| | `web_search` | `query`(required), `platform`/`min_results`/`max_results`(optional) | `[{title,url,content}]` | Multi-source aggregation/fact-checking/latest information | | `web_fetch` | `url`(required) | Structured Markdown | Complete content acquisition/in-depth analysis | | `get_config_info` | None | `{api_url,status,test}` | Connection diagnosis | | `switch_model` | `model`(required) | `{status,previous_model,current_model}` | Switch Grok model/performance optimization | | `toggle_builtin_tools` | `action`(optional: on/off/status) | `{blocked,deny_list,file}` | Disable/enable official tools | ## Execution strategy **Query construction**: Use `web_search` for breadth, `web_fetch` for depth, and set the `platform` parameter for specific platforms **Search execution**: Prioritize summary → Supplement complete content with key URLs → Adjust query and retry if results are insufficient (prohibit giving up) **Result integration**: Cross-validation + **mandatory source labeling** `[title](URL)` + indicate date for time-sensitive information ## Error recovery Connection failed → `get_config_info` check | No results → Relax query conditions | Timeout → Search for alternative sources ## Core constraints ✅ Mandatory GrokSearch tool + output must include source reference + must retry if failed + must verify key information ❌ Prohibit output without source + prohibit single abandonment + prohibit unverified assumptions ``` #### Detailed version prompt <details> <summary><b>💡 Grok Search Enhance System Prompt (Detailed Version)</b> (Click to expand)</summary> ````markdown # Grok Search Enhance System Prompt (Detailed Version) ## 0. Module Activation **Trigger Condition**: Automatically activate this module when the following operations need to be performed: - Network search / information retrieval / fact-checking - Get web page content / URL parsing / document crawling - Query the latest information / break through the knowledge cutoff limit ## 1. Tool Routing Policy ### Mandatory Replacement Rules | Demand Scenario | ❌ Disable (Built-in) | ✅ Mandatory Use (GrokSearch) | | :--- | :--- | :--- | | Network Search | `WebSearch` | `mcp__grok-search__web_search` | | Web Page Crawling | `WebFetch` | `mcp__grok-search__web_fetch` | | Configuration Diagnosis | N/A | `mcp__grok-search__get_config_info` | ### Tool Capability Matrix | Tool | Parameters | Output | Use Case | |------|------------|--------|----------| | `web_search` | `query`(required), `platform`/`min_results`/`max_results`(optional) | `[{title,url,content}]` | Multi-source aggregation/fact-checking/latest information | | `web_fetch` | `url`(required) | Structured Markdown | Complete content acquisition/in-depth analysis | | `get_config_info` | None | `{api_url,status,test}` | Connection diagnosis | | `switch_model` | `model`(required) | `{status,previous_model,current_model}` | Switch Grok model/performance optimization | | `toggle_builtin_tools` | `action`(optional: on/off/status) | `{blocked,deny_list,file}` | Disable/enable official tools | ## 2. Search Workflow ### Phase 1: Query Construction 1. **Intent Recognition**: Analyze user needs and determine the search type: - **Breadth Search**: Multi-source information aggregation → Use `web_search` - **Depth Acquisition**: Complete content of a single URL → Use `web_fetch` 2. **Parameter Optimization**: - If you need to focus on a specific platform, set the `platform` parameter - Adjust `min_results` / `max_results` according to the complexity of the demand ### Phase 2: Search Execution 1. **Preferred Strategy**: Prioritize using `web_search` to obtain structured summaries 2. **Depth Supplement**: If the summary is not enough to answer the question, call `web_fetch` for key URLs to obtain complete content 3. **Iterative Retrieval**: If the first round of results does not meet the requirements, **adjust the query terms** and search again (prohibit direct abandonment) ### Phase 3: Result Synthesis 1. **Information Verification**: Cross-compare multi-source results to identify contradictory information 2. **Timeliness Labeling**: For time-sensitive information, **must** label the information source and time 3. **Reference Specification**: The output **must include** the source URL, format: `[title](URL)` ## 3. Error Handling | Error Type | Diagnosis Method | Recovery Strategy | | :--- | :--- | :--- | | Connection Failed | Call `get_config_info` to check the configuration | Prompt the user to check the API URL / Key | | No Search Results | Check whether the query is too specific | Relax the search terms and remove the limiting conditions | | Web Page Crawling Timeout | Check the accessibility of the URL | Try searching for alternative sources | | Content is Truncated | Check the structure of the target page | Crawl in segments or prompt the user to visit directly | ## 4. Anti-Patterns | ❌ Prohibited Behavior | ✅ Correct Approach | | :--- | :--- | | Do not label the source after searching | The output **must** include `[Source](URL)` reference | | Give up after a single search failure | Retry at least once after adjusting the parameters | | Assume web page content without crawling | **Must** call `web_fetch` to verify key information | | Ignore the timeliness of search results | Time-sensitive information **must** be labeled with the date | --- Module Description: - Mandatory Replacement: Explicitly disable built-in tools and force routing to GrokSearch - Three Tool Coverage: web_search + web_fetch + get_config_info - Error Handling: Includes recovery strategies for configuration diagnosis - Reference Specification: Mandatory source labeling, in line with information traceability requirements ```` </details> ### Detailed Project Introduction #### MCP Tool Description This project provides five MCP tools: ##### `web_search` - Web Search | Parameter | Type | Required | Default Value | Description | |------|------|------|--------|------| | `query` | string | ✅ | - | Search query statement | | `platform` | string | ❌ | `""` | Focus on search platform (such as `"Twitter"`, `"GitHub, Reddit"`) | | `min_results` | int | ❌ | `3` | Minimum number of results returned | | `max_results` | int | ❌ | `10` | Maximum number of results returned | **Return**: JSON array containing `title`, `url`, `content` <details> <summary><b>Return Example</b> (Click to expand)</summary> ```json [ { "title": "Claude Code - Anthropic Official CLI Tool", "url": "https://claude.com/claude-code", "description": "Anthropic's official command line tool, supports MCP protocol integration, provides code generation and project management functions" }, { "title": "Model Context Protocol (MCP) Technical Specification", "url": "https://modelcontextprotocol.io/docs", "description": "MCP protocol official document, defines the standardized communication interface between AI models and external tools" }, { ... } ] ``` </details> ##### `web_fetch` - Web Page Content Crawling | Parameter | Type | Required | Description | |------|------|------|------| | `url` | string | ✅ | Target web page URL | **Function**: Get the complete web page content and convert it into structured Markdown, retaining title levels, lists, tables, code blocks and other elements <details> <summary><b>Return Example</b> (Click to expand)</summary> ```markdown --- source: https://modelcontextprotocol.io/docs/concepts/architecture title: MCP Architecture Design Document fetched_at: 2024-01-15T10:30:00Z --- # MCP Architecture Design Document ## Table of Contents - [Core Concepts](#core-concepts) - [Protocol Levels](#protocol-levels) - [Communication Mode](#communication-mode) ## Core Concepts Model Context Protocol (MCP) is a standardized communication protocol used to connect AI models with external tools and data sources. ... For more information, please visit [Official Documentation](https://modelcontextprotocol.io) ``` </details> ##### `get_config_info` - Configuration Information Query **No parameters required**. Display configuration status, test API connection, return response time and number of available models (API Key automatically desensitized) <details> <summary><b>Return Example</b> (Click to expand)</summary> ```json { "api_url": "https://YOUR-API-URL/grok/v1", "api_key": "sk-a*****************xyz", "config_status": "✅ Configuration Complete", "connection_test": { "status": "✅ Connection Successful", "message": "Successfully obtained the model list (HTTP 200), a total of x models", "response_time_ms": 234.56 } } ``` </details> ##### `switch_model` - Model Switching | Parameter | Type | Required | Description | |------|------|------|------| | `model` | string | ✅ | The model ID to switch to (e.g., `"grok-4-fast"`, `"grok-2-latest"`, `"grok-vision-beta"`) | **Functionality**: - Switches the default Grok model used for search and fetch operations - Configuration is automatically persisted to `~/.config/grok-search/config.json` - Supports persistent settings across sessions - Suitable for performance optimization or quality comparison testing <details> <summary><b>Return Example</b> (Click to expand)</summary> ```json { "status": "✅ 成功", "previous_model": "grok-4-fast", "current_model": "grok-2-latest", "message": "模型已从 grok-4-fast 切换到 grok-2-latest", "config_file": "/home/user/.config/grok-search/config.json" } ``` **Usage Example**: In a Claude conversation, enter: ``` Please switch the Grok model to grok-2-latest ``` Or say directly: ``` Switch model to grok-vision-beta ``` </details> ##### `toggle_builtin_tools` - Tool Routing Control | Parameter | Type | Required | Default | Description | |------|------|------|--------|------| | `action` | string | ❌ | `"status"` | Action type: `"on"`/`"enable"` (disable official tools), `"off"`/`"disable"` (enable official tools), `"status"`/`"check"` (check status) | **Functionality**: - Controls the `permissions.deny` configuration in the project-level `.claude/settings.json` - Disables/enables Claude Code's official `WebSearch` and `WebFetch` tools - Forces routing to the GrokSearch MCP tool - Automatically locates the project root directory (by searching for `.git`) - Preserves other configuration items <details> <summary><b>Return Example</b> (Click to expand)</summary> ```json { "blocked": true, "deny_list": ["WebFetch", "WebSearch"], "file": "/path/to/project/.claude/settings.json", "message": "官方工具已禁用" } ``` **Usage Example**: ``` # Disable official tools (recommended) Disable the official search and fetch tools # Enable official tools Enable the official search and fetch tools # Check current status Show the disabled status of official tools ``` </details> --- <details> <summary><h2>Project Architecture</h2> (Click to expand)</summary> ``` src/grok_search/ ├── config.py # Configuration management (environment variables) ├── server.py # MCP Server entry point (tool registration) ├── logger.py # Logging system ├── utils.py # Formatting tools └── providers/ ├── base.py # SearchProvider base class └── grok.py # Grok API implementation ``` </details> ## Common Issues **Q: How do I obtain Grok API access?** A: Register with a third-party platform → Obtain API Endpoint and Key → Configure using `claude mcp add-json` **Q: How do I verify the configuration after setting it up?** A: In a Claude conversation, say "显示 grok-search 配置信息", and check the connection test results ## License This project is open-sourced under the [MIT License](LICENSE). --- <div align="center"> **If this project is helpful to you, please give it a ⭐ Star!** [](https://www.star-history.com/#GuDaStudio/GrokSearch&type=date&legend=top-left) </div>