grok-search-mcp

MCP server for using the local Grok CLI as a search tool from Codex.

This project exists to give coding agents a better search lane when the default search experience is not enough. Grok's search, especially for X/Twitter content, is often noticeably better than what Codex or Claude Code can reach on their own. grok-search-mcp exposes that advantage through a small MCP server, so an agent can ask Grok for web or X search results without turning Grok into a general chat dependency.

This project is intentionally narrow:

• no xAI API key

• no API credits

• no image or video tools

• no generic Grok chat tool

• only web search and X/Twitter search through grok

The server runs grok with an isolated HOME, so it does not load your normal Cursor/Claude/Grok user-level MCP servers, hooks, or skills.

Tools

Both tools return a JSON string with this shape:

{
  "summary": "short summary",
  "items": [],
  "urls": [],
  "rawText": "raw Grok answer",
  "diagnostics": {
    "mode": "x",
    "parseOk": true,
    "model": "grok-build",
    "isolatedHome": "/Users/me/.grok-search-mcp",
    "warnings": []
  }
}

If Grok does not return parseable JSON, the server keeps the raw answer and sets diagnostics.parseOk=false.

Related MCP server: free-search-mcp

Requirements

• Node.js 20+

• The official Grok CLI installed

• A Grok CLI account/subscription that can use search

Install Grok CLI if needed:

curl -fsSL https://x.ai/cli/install.sh | bash

One-time login

The MCP server uses a dedicated profile home, defaulting to ~/.grok-search-mcp. Log in once for that isolated profile:

GROK_BIN="/Users/zhangyuze/.grok/bin/grok" \
GROK_SEARCH_MCP_HOME="$HOME/.grok-search-mcp" \
npx -y github:z2z23n0/grok-search-mcp login

You do not need to log in for every search. Run this again only if the isolated profile token expires or is revoked.

Check the setup:

GROK_BIN="/Users/zhangyuze/.grok/bin/grok" \
GROK_SEARCH_MCP_HOME="$HOME/.grok-search-mcp" \
npx -y github:z2z23n0/grok-search-mcp doctor

doctor should report:

{
  "ok": true,
  "authenticated": true,
  "isolation": {
    "hooks": 0,
    "skills": 0,
    "mcpServers": 0
  }
}

Codex config

Add this to ~/.codex/config.toml:

[mcp_servers.grok_search]
command = "npx"
args = ["-y", "github:z2z23n0/grok-search-mcp"]
enabled_tools = ["grok_x_search", "grok_web_search"]
default_tools_approval_mode = "auto"
startup_timeout_sec = 120
tool_timeout_sec = 240

[mcp_servers.grok_search.env]
GROK_BIN = "/Users/zhangyuze/.grok/bin/grok"
GROK_SEARCH_MCP_HOME = "/Users/zhangyuze/.grok-search-mcp"
GROK_SEARCH_MCP_MODEL = "grok-build"
NPM_CONFIG_REGISTRY = "https://registry.npmjs.org"

Restart Codex after editing MCP config.

Example prompts:

Use grok_search.grok_x_search to search X for recent @grok posts about Grok CLI.

Use grok_search.grok_web_search to search docs.x.ai for Grok Build headless scripting.

Environment

The server sets these for the Grok subprocess:

• HOME=$GROK_SEARCH_MCP_HOME

• XDG_CONFIG_HOME=$GROK_SEARCH_MCP_HOME/.config

• XDG_CACHE_HOME=$GROK_SEARCH_MCP_HOME/.cache

• XDG_DATA_HOME=$GROK_SEARCH_MCP_HOME/.local/share

It also runs Grok from a temporary empty working directory instead of your repo.

Local development

npm install
npm test
npm run typecheck
npm run build

Integration tests are skipped by default because they require a logged-in isolated Grok profile:

RUN_GROK_INTEGRATION=1 npm run test:integration

Notes

grok_x_search relies on Grok CLI agent runtime behavior. It does not call the public xAI API x_search tool, so it avoids API billing but cannot promise API level filtering or schemas.