grok-web-search-mcp

Language: English | 中文

About The Project

Agents need live web and X access with citations, not just a chat completion. This project wraps xAI’s server-side web_search and x_search tools as a single MCP tool, so hosts like Grok, Cursor, or Claude Desktop can call them without embedding xAI client logic.

Repository: https://github.com/NakanoSanku/grok-web-search-mcp

Upstream call (simplified):

POST {base_url}/responses
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "model": "grok-4.5",
  "input": [{"role": "user", "content": "<query>"}],
  "tools": [
    {"type": "web_search", "enable_image_understanding": true},
    {
      "type": "x_search",
      "allowed_x_handles": ["xai"],
      "from_date": "2025-10-01",
      "to_date": "2025-10-10",
      "enable_image_understanding": true,
      "enable_video_understanding": true
    }
  ]
}

Design goals:

• One MCP tool, one calling contract — models may only pass query / scope / recency / images

• Lean results — query / text / citations / sources_used (no raw upstream dump)

• Custom base URL — official https://api.x.ai/v1 or OpenAI-compatible proxies

• Optional vision input — attach https URLs or data URIs (local paths are opt-in)

• No PyPI required — run directly from GitHub with uvx --from git+...

Features

Not included: enable_image_search (web image gallery embedding). Use images when you provide a picture; use enable_image_understanding for images on browsed pages and X posts.

Built With

Related MCP server: WebQuest MCP

Getting Started

Prerequisites

• Python 3.10+

• An xAI API key (or a key for a compatible gateway)

• uv (recommended for uvx from GitHub)

# optional: install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Quick start (uvx from GitHub)

No local clone required for day-to-day MCP use:

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

Pin a branch, tag, or commit when you need reproducibility:

uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main grok-web-search-mcp
# uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@v0.3.0 grok-web-search-mcp

Local development install

1. Clone the repository:

   git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
   cd grok-web-search-mcp

2. Install dependencies:

   uv sync
   # or: pip install -e ".[dev]"

3. Create a local env file:

   cp .env.example .env

4. Edit .env and set at least GROK_API_KEY (see Configuration).

Configuration

Keep secrets out of git. Prefer host-injected env for MCP configs when possible.

Usage

Run the Server

Recommended (from GitHub):

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

From a local checkout:

export GROK_API_KEY=xai-...
# Windows PowerShell: $env:GROK_API_KEY="xai-..."

uv run grok-web-search-mcp
# or
uv run python -m grok_web_search_mcp

Compatible proxy example:

export GROK_API_KEY=sk-xxx
export GROK_BASE_URL=http://127.0.0.1:8317/v1
export GROK_MODEL=grok-4.5
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

MCP Host Config

Preferred: run from GitHub with uvx (no local path).

JSON-style hosts (Cursor / Claude Desktop, etc.):

{
  "mcpServers": {
    "grok-web-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
        "grok-web-search-mcp"
      ],
      "env": {
        "GROK_API_KEY": "xai-your-key",
        "GROK_BASE_URL": "https://api.x.ai/v1",
        "GROK_MODEL": "grok-4.5"
      }
    }
  }
}

Grok user config (~/.grok/config.toml):

[mcp_servers.grok-web-search]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
  "grok-web-search-mcp",
]
enabled = true

[mcp_servers.grok-web-search.env]
GROK_API_KEY = "xai-your-key"
GROK_BASE_URL = "https://api.x.ai/v1"
GROK_MODEL = "grok-4.5"

Pin a ref (branch / tag / commit):

args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main",
  "grok-web-search-mcp",
]

Local development only (absolute path to a checkout):

[mcp_servers.grok-web-search]
command = "uv"
args = [
  "run",
  "--directory",
  "/absolute/path/to/grok-web-search-mcp",
  "grok-web-search-mcp",
]
enabled = true

Tool: web_search

Every host model must use the same four-key contract. Extra arguments (model, reasoning_effort, system_prompt, domain/handle filters) are rejected. Quality knobs live in environment variables so search behavior does not drift between models.

Canonical example:

{ "query": "What is xAI's latest valuation?" }

The server then: normalizes query, injects a fixed system prompt, applies operator filters from env, maps recency to X date bounds, and always uses the configured model / reasoning effort.

images are Responses API input_image parts. Local filesystem paths are disabled by default. This is not “search the web for stock images.”

Response Shape

Success (MCP isError: false, structured content):

{
  "query": "What is xAI?",
  "text": "...",
  "citations": [{"url": "https://x.ai", "title": "xAI"}],
  "sources_used": ["web", "x"],
  "scope": "all",
  "recency": "any"
}

Failure is a protocol-level tool error (isError: true) with a short message, for example Grok API error (401): Invalid API key. Incomplete or empty upstream responses are also errors, not silent success.

Intentionally not returned: API key, model, base_url, raw upstream JSON, or annotation blobs (URLs are mined into citations only). Diagnose config outside the tool result (env / host MCP settings / stderr logs).

Python Client Example

import asyncio
from grok_web_search_mcp.client import GrokWebSearchClient
from grok_web_search_mcp.config import Settings

async def main():
    async with GrokWebSearchClient(Settings.from_env()) as client:
        result = await client.web_search("What is xAI?")
        print(result.to_dict())

asyncio.run(main())

Real calls consume model + server-side search quota. Unit tests use mocks and do not hit the network.

Development

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp
uv sync --extra dev
uv run pytest
# live API (optional): GROK_LIVE=1 uv run pytest -m live

Project layout:

src/grok_web_search_mcp/
  server.py    # MCP tool surface
  client.py    # Responses API client + image helpers
  config.py    # Environment settings
tests/

Roadmap

• Single lean web_search MCP tool

• Enable upstream web_search and x_search by default

• X handle/date filters and image/video understanding

• Custom base_url / proxy support

• Domain allow/deny filters

• Optional multimodal image input

• Install / run from GitHub via uvx

• Protocol-level errors, retries, timeout/reasoning defaults

• Local-image jail (disabled by default)

• Canonical MCP calling contract (query / scope / recency / images)

• Optional Streamable HTTP transport docs/examples

• Golden-set evaluation harness for search quality

See the open issues.

Contributing

Contributions are welcome.

1. Fork the project

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

Please keep the tool surface lean: prefer one well-documented tool over many thin wrappers.

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

• Best-README-Template

• xAI Web Search

• xAI X Search

• Model Context Protocol

• FastMCP

• uv