grok-search

Rust rewrite of the grok-with-tavily MCP server using the official modelcontextprotocol/rust-sdk.

Status

• Transport:
  • stdio: implemented and intended as the default for Claude Code, Codex, and Gemini CLI
  • streamable HTTP at /mcp: implemented
  • legacy SSE compatibility paths /sse and /messages: implemented for older MCP SSE clients
• Tools:
  • implemented: web_search, get_sources, web_fetch, web_map, get_config_info, switch_model, toggle_builtin_tools, all plan_* tools
• Migration:
  • ~/.config/grok-search/config.json is preserved
  • GUDA_* is still accepted as a deprecated runtime fallback, but is no longer documented

Verified Locally

• cargo check: passed
• cargo test: passed
• cargo install --path . --root /tmp/grok-search-install: passed

GitHub Releases are generated by cargo-dist. npm, crates.io, and Docker publishing are handled by separate workflows.

Install

Cargo

cargo install --path .

Planned release install:

cargo install grok-search

NPX

Published package:

npx -y @un4gt/grok-search

The npm package now uses platform-specific packages that embed native binaries, instead of downloading release artifacts at install time.

Configuration

Required:

• GROK_API_URL
• GROK_API_KEY

Optional:

• GROK_MODEL
• TAVILY_ENABLED
• TAVILY_API_URL
• TAVILY_API_KEY
• FIRECRAWL_API_URL
• FIRECRAWL_API_KEY
• GROK_DEBUG
• GROK_LOG_LEVEL
• GROK_LOG_DIR
• GROK_RETRY_MAX_ATTEMPTS
• GROK_RETRY_MULTIPLIER
• GROK_RETRY_MAX_WAIT

Run

STDIO

grok-search

HTTP

grok-search http --bind 127.0.0.1:8000

The MCP endpoint is http://127.0.0.1:8000/mcp.

Health probe:

curl http://127.0.0.1:8000/health

Agent Setup

Claude Code

Unix-like systems:

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@un4gt/grok-search"],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key"
  }
}

Native Windows:

{
  "type": "stdio",
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@un4gt/grok-search"],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key"
  }
}

Codex

Use npx on Unix-like systems or a direct binary path on Windows in ~/.codex/config.toml.

Gemini CLI

Add the server under mcpServers in ~/.gemini/settings.json, again preferring npx on Unix-like systems and the built binary on Windows.

Docker

Build:

docker build -t grok-search:local .

Run as a remote MCP server over streamable HTTP:

docker run --rm -p 8000:8000 \
  -e GROK_API_URL=https://your-api-endpoint.com/v1 \
  -e GROK_API_KEY=your-grok-api-key \
  grok-search:local

Then connect clients to:

http://127.0.0.1:8000/mcp

Compose:

docker compose up --build

For local same-machine agent integration, Docker can also be used with stdio, but that requires docker run -i and is less ergonomic than running the native binary directly.

Verify

cargo check
cargo test