GrokSearch-Codex-MCP

 <div align="center"> <!-- # Grok Search MCP --> [English](./docs/README_EN.md) | **Grok-with-Tavily MCP, providing more comprehensive web access capabilities for Codex** [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/jlowin/fastmcp) </div> --- ## I. Overview Grok Search MCP is a MCP server built based on [FastMCP](https://github.com/jlowin/fastmcp), adopting a **dual-engine architecture**: **Grok** is responsible for AI-driven intelligent search, and **Tavily** is responsible for high-fidelity web scraping and site mapping, each taking its strengths to provide Codex with complete real-time web access capabilities. ### Project Origin and Modification Description This project is modified from [GuDaStudio/GrokSearch](https://github.com/GuDaStudio/GrokSearch), retaining the original project's Grok search, Tavily crawling/mapping, and Firecrawl degradation capabilities. The main purpose of this branch is to make the MCP service run more stably as a **Codex available online search tool**: fix the configuration problem of OpenAI compatible interface bare domain name missing `/v1`, enhance `/models` and streaming response format verification, avoid upstream returning HTML or empty response being misjudged as successful; at the same time, supplement `TAVILY_ENABLED` switch effective logic, additional source allocation strategy, Codex stdio MCP instructions, `get_codex_setup` configuration auxiliary tool, and project-level `.codex/config.toml` example. These changes aim to reduce the probability of empty return and misconfiguration when Codex calls search/scraping tools, and make it easier for users to access the MCP through `codex mcp add` or local `.codex/config.toml`. ``` Codex ──MCP──► Grok Search Server ├─ web_search ───► Grok API（AI search） ├─ web_fetch ───► Tavily Extract → Firecrawl Scrape（content crawling, automatic degradation） └─ web_map ───► Tavily Map（site mapping） ``` ### Features - **Dual Engines**: Grok search + Tavily crawling/mapping, complementary collaboration - **Firecrawl Backup**: Automatically degrade to Firecrawl Scrape when Tavily extraction fails, supporting automatic retry of empty content - **OpenAI Compatible Interface**, supporting any Grok mirror site - **Codex Compatible**: providing stdio MCP server instructions, Codex configuration examples, and `get_codex_setup` configuration auxiliary tool - **Automatic Time Injection** (detecting time-related queries, injecting local time context) - Intelligent retry (supporting Retry-After header parsing + exponential backoff) - Parent process monitoring (automatically detecting parent process exit under Windows to prevent zombie processes) ## II. Installation ### Prerequisites - Python 3.10+ - [uv](https://docs.astral.sh/uv/getting-started/installation/)（recommended Python package manager） - Codex - If installing from a private GitHub repository, ensure that the current terminal has access to the repository through `gh auth login` or Git credentials <details> <summary><b>Install uv</b></summary> ```bash # Linux/macOS curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` > Windows users can run directly in PowerShell; if encountering certificate issues, refer to the `--native-tls` example below. </details> ### Install to Codex (Recommended) If previously installed a MCP with the same name, remove the old configuration first: ```powershell codex mcp remove grok-search ``` Then install the current project: ```powershell codex mcp add grok-search ` --env GROK_API_URL=https://your-api-endpoint.com/v1 ` --env GROK_API_KEY=your-grok-api-key ` --env GROK_MODEL=grok-4-fast ` --env TAVILY_API_KEY=tvly-your-tavily-key ` --env TAVILY_API_URL=https://api.tavily.com ` -- uvx --from git+https://github.com/losalexandra/GrokSearch-Codex-MCP grok-search ``` Description: - `GROK_API_URL` needs to be in OpenAI compatible format; if only the bare domain name is provided, the program will automatically append `/v1`. - `GROK_API_KEY` is required. - `GROK_MODEL` is optional, defaulting to `grok-4-fast`. - `TAVILY_API_KEY` is optional; if not configured, `web_fetch` / `web_map` will be unavailable. - Actual keys should not be written to the repository and should be passed through `codex mcp add --env`, user-level `~/.codex/config.toml`, or current terminal environment variables. Verify Codex configuration: ```powershell codex mcp list codex mcp get grok-search ``` Enter Codex and call: ```text Call grok-search get_config_info to check configuration ``` ### Local Development Mode This repository contains a project-level `.codex/config.toml`: ```toml [mcp_servers.grok-search] command = "uv" args = ["run", "grok-search"] ``` When starting Codex in the current repository, it can directly read this configuration and run the MCP with local source code. This method is suitable for development and debugging; keys should still not be written to `.codex/config.toml`. ### Claude Usage Instructions This repository is adapted and documented for Codex. If you need to use Grok Search MCP in Claude / Claude Code, it is recommended to use the original author's repository: [GuDaStudio/GrokSearch](https://github.com/GuDaStudio/GrokSearch). ### Environment Variables | Variable | Required | Default Value | Description | |----------|----------|---------------|-------------| | `GROK_API_URL` | ✅ | - | Grok API address (OpenAI compatible format) | | `GROK_API_KEY` | ✅ | - | Grok API key | | `GROK_MODEL` | ❌ | `grok-4-fast` | Default model (overrides `~/.config/grok-search/config.json` if set) | | `TAVILY_API_KEY` | ❌ | - | Tavily API key (for `web_fetch` / `web_map`) | | `TAVILY_API_URL` | ❌ | `https://api.tavily.com` | Tavily API address | | `TAVILY_ENABLED` | ❌ | `true` | Whether to enable Tavily | | `FIRECRAWL_API_KEY` | ❌ | - | Firecrawl API key (backup for Tavily failure) | | `FIRECRAWL_API_URL` | ❌ | `https://api.firecrawl.dev/v2` | Firecrawl API address | | `GROK_DEBUG` | ❌ | `false` | Debug mode | | `GROK_LOG_LEVEL` | ❌ | `INFO` | Log level | | `GROK_LOG_DIR` | ❌ | `logs` | Log directory | | `GROK_RETRY_MAX_ATTEMPTS` | ❌ | `3` | Maximum retry attempts | | `GROK_RETRY_MULTIPLIER` | ❌ | `1` | Retry backoff multiplier | | `GROK_RETRY_MAX_WAIT` | ❌ | `10` | Maximum retry wait seconds | ## III. MCP Tool Introduction <details> <summary>This project provides multiple MCP tools (expand to view)</summary> ### `web_search` — AI Web Search Execute AI-driven web search through Grok API, returning only Grok's response content and `session_id` for subsequent source retrieval. `web_search` output does not expand sources, only returns `sources_count`; sources are cached on the server by `session_id` and can be pulled using `get_sources`. | Parameter | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| | `query` | string | ✅ | - | Search query | | `platform` | string | ❌ | `""` | Focus platform (e.g., `"Twitter"`, `"GitHub, Reddit"`) | | `model` | string | ❌ | `null` | Specify Grok model ID by session | | `extra_sources` | int | ❌ | `0` | Additional source quantity (Tavily/Firecrawl, can be 0 to disable) | Automatically detect time-related keywords in queries (e.g., "latest", "today", "recent"), injecting local time context to improve timeliness search accuracy. Return value (structured dictionary): - `session_id`: This query's session ID - `content`: Grok response content (automatically stripped of sources) - `sources_count`: Cached source quantity ### `get_sources` — Get Sources Retrieve all sources for a corresponding `web_search` by `session_id`. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `session_id` | string | ✅ | `web_search` returned `session_id` | Return value (structured dictionary): - `session_id` - `sources_count` - `sources`: Source list (each item contains `url`, may contain `title`/`description`/`provider`) ### `web_fetch` — Web Content Crawling Obtain complete web content through Tavily Extract API, returning Markdown format. Automatically degrade to Firecrawl Scrape for backup crawling when Tavily fails. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | ✅ | Target webpage URL | ### `web_map` — Site Structure Mapping Traverse website structure through Tavily Map API, discover URLs, and generate site maps. | Parameter | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| | `url` | string | ✅ | - | Starting URL | | `instructions` | string | ❌ | `""` | Natural language filtering instructions | | `max_depth` | int | ❌ | `1` | Maximum traversal depth (1-5) | | `max_breadth` | int | ❌ | `20` | Maximum tracked links per page (1-500) | | `limit` | int | ❌ | `50` | Total link processing limit (1-500) | | `timeout` | int | ❌ | `150` | Timeout seconds (10-150) | ### `get_config_info` — Configuration Diagnosis No parameters. Display all configuration status, test Grok API connection, return response time, and available model list (API Key automatically desensitized). ### `get_codex_setup` — Codex Configuration Assistant No parameters. Return Codex stdio MCP's `codex mcp add` command and `config.toml` example, with all keys presented as placeholders. ### `switch_model` — Model Switching | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `model` | string | ✅ | Model ID (e.g., `"grok-4-fast"`, `"grok-2-latest"`) | After switching, configuration persists to `~/.config/grok-search/config.json`, maintaining across sessions. ### `search_planning` — Search Planning Structured search planning scaffolding (multi-stage, multi-round) for generating executable search plans before executing complex searches. </details> ## IV. Frequently Asked Questions <details> <summary> Q: Must Grok and Tavily be configured simultaneously? </summary> A: Grok (`GROK_API_URL` + `GROK_API_KEY`) is required, providing core search capabilities. Tavily and Firecrawl are optional: configuring Tavily makes `web_fetch` prefer Tavily Extract, degrading to Firecrawl Scrape upon failure; if neither is configured, `web_fetch` returns a configuration error prompt. `web_map` depends on Tavily. </details> <details> <summary> Q: What format should the Grok API address be in? </summary> A: Needs to be in OpenAI compatible format (supporting `/chat/completions` and `/models` endpoints). If using the official Grok, access through a mirror site compatible with OpenAI format. </details> <details> <summary> Q: How to verify configuration? </summary> A: In Codex, call `grok-search get_config_info`; the tool will automatically test API connection, display model list, configuration status, and desensitized key information. </details> ## License [MIT License](LICENSE) --- <div align="center"> **If this project helps you, give it a Star!** [](https://www.star-history.com/#losalexandra/GrokSearch-Codex-MCP&type=date&legend=top-left) </div>