Grok Search MCP

A local stdio MCP server that exposes xAI-compatible server-side search through a Responses API relay.

Tools

• grok_web_search: public web search with optional allowed or excluded domains.
• grok_x_search: X post/profile/thread search. This is deliberately separate and marked high-cost because one request can expand into many metered tool calls.

Both tools report citations, actual upstream tool-call counts, token usage, the effective model, and the relay's raw cost_in_usd_ticks value when present.

Configuration

Required at call time:

BOTCF_API_KEY

On Windows, run npm run setup for the first-install configuration window. Enter Base URLs, models, and API keys separated by semicolons; the positions are paired, and one model value may be reused for every provider. Public provider settings are stored in config.json, while the complete provider array including keys is stored as a current-user DPAPI ciphertext under %APPDATA%\grok-search-mcp\api-key.dpapi.

Requests rotate across configured providers. Recoverable network/timeout, authentication, rate-limit, route/model compatibility, and 5xx failures can switch to the next distinct provider. Each provider is attempted at most once and each MCP call has a hard maximum of three provider attempts. A failover can still duplicate upstream work if a provider accepted a request before its response was lost, so account-side spend limits remain necessary.

For CI or temporary sessions, GROK_SEARCH_PROVIDERS may contain a JSON provider array. The legacy BOTCF_API_KEY, BOTCF_BASE_URL, and GROK_SEARCH_MODEL variables remain supported.

Optional:

BOTCF_BASE_URL=https://botcf.com
GROK_SEARCH_MODEL=grok-4.5

The server starts and lists tools without a key, then fails closed with a clear error if a tool is called before BOTCF_API_KEY is configured. Secrets are never accepted as tool arguments or printed.

Each installation must use its own provider credentials. Do not share .env files, DPAPI ciphertext, setup screenshots, or API keys with other users.

Development

npm install
npm run check

Codex configuration

After building, register the compiled entry point and forward only the required environment variable:

[mcp_servers.grok_search]
command = "node"
args = ["D:/path/to/grok-search-mcp/dist/index.js"]
env_vars = ["GROK_SEARCH_PROVIDERS", "BOTCF_API_KEYS", "BOTCF_API_KEY", "GROK_SEARCH_BASE_URLS", "BOTCF_BASE_URL", "GROK_SEARCH_MODELS", "GROK_SEARCH_MODEL"]
startup_timeout_sec = 20
tool_timeout_sec = 180

No request is retried automatically. HTTP redirects are rejected so the API key cannot be forwarded to another origin.