grok-web-search-mcp

<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 --> <a id="readme-top"></a>

<!-- LANGUAGE --> Language: English | 中文

<!-- PROJECT SHIELDS --> [![Python][python-shield]][python-url] [![License: MIT][license-shield]][license-url] [![MCP][mcp-shield]][mcp-url] [![xAI][xai-shield]][xai-web-search-url] [![GitHub][github-shield]][github-url]

<!-- PROJECT LOGO / TITLE --> <br /> <div align="center"> <h3 align="center">grok-web-search-mcp</h3> <p align="center"> A lean FastMCP server that exposes Grok / xAI Responses API <code>web_search</code> + <code>x_search</code> to any MCP host — with custom <code>base_url</code> for official API or compatible proxies. <br /> <br /> <a href="https://github.com/NakanoSanku/grok-web-search-mcp"><strong>Explore the repo »</strong></a> · <a href="https://docs.x.ai/developers/tools/web-search"><strong>xAI Web Search docs »</strong></a> · <a href="./README_CN.md"><strong>中文文档 »</strong></a> </p> </div>

<!-- TABLE OF CONTENTS --> <details> <summary>Table of Contents</summary> <ol> <li> <a href="#about-the-project">About The Project</a> <ul> <li><a href="#features">Features</a></li> <li><a href="#built-with">Built With</a></li> </ul> </li> <li> <a href="#getting-started">Getting Started</a> <ul> <li><a href="#prerequisites">Prerequisites</a></li> <li><a href="#quick-start-uvx-from-github">Quick start (uvx from GitHub)</a></li> <li><a href="#local-development-install">Local development install</a></li> </ul> </li> <li><a href="#configuration">Configuration</a></li> <li> <a href="#usage">Usage</a> <ul> <li><a href="#run-the-server">Run the Server</a></li> <li><a href="#mcp-host-config">MCP Host Config</a></li> <li><a href="#tool-web_search">Tool: web_search</a></li> <li><a href="#response-shape">Response Shape</a></li> <li><a href="#python-client-example">Python Client Example</a></li> </ul> </li> <li><a href="#development">Development</a></li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#acknowledgments">Acknowledgments</a></li> </ol> </details>

<!-- ABOUT THE PROJECT -->

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 — web_search enables both upstream web and X search
• Lean results — ok / query / text / citations (no raw upstream dump)
• Custom base URL — official https://api.x.ai/v1 or OpenAI-compatible proxies
• Optional vision input — attach images (URL, data URI, or local path) for visual + search questions
• No PyPI required — run directly from GitHub with uvx --from git+...

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Features

Capability	Notes
Live web search	Grok synthesizes an answer with source URLs
Live X search	x_search is included in every upstream request by default
X filters	Handle allow/deny lists (max 20) and inclusive date range
Domain filters	Allowlist or denylist (max 5, mutually exclusive)
Search media understanding	Images on web pages and X posts; videos on X posts
Client image input	Optional images for “ask about this picture + search”
Lean JSON output	No model / base_url / annotations / raw payload in tool results
Proxy-friendly	GROK_BASE_URL / XAI_BASE_URL
GitHub install	uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git

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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Built With

• [![Python][python-shield]][python-url]
• [![FastMCP][fastmcp-shield]][fastmcp-url]
• [![httpx][httpx-shield]][httpx-url]
• [![xAI API][xai-shield]][xai-url]
• [![MCP][mcp-shield]][mcp-url]
• [![uv][uv-shield]][uv-url]

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->

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.1.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).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Configuration

Variable	Required	Default	Description
GROK_API_KEY	Yes	—	Also accepts XAI_API_KEY / GROK_WEB_SEARCH_API_KEY
GROK_BASE_URL	No	https://api.x.ai/v1	Also XAI_BASE_URL / GROK_WEB_SEARCH_BASE_URL
GROK_MODEL	No	grok-4.5	Also XAI_MODEL
GROK_TIMEOUT	No	120	Request timeout (seconds)
GROK_ENABLE_IMAGE_UNDERSTANDING	No	true	Analyze images on browsed pages and X posts
GROK_REASONING_EFFORT	No	high	Default thinking length for reasoning models: low / medium / high; also XAI_REASONING_EFFORT

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE -->

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Tool: web_search

Parameter	Type	Description
query	string	Search question (required)
model	string?	Override default model
allowed_domains	string?	Web-search allowlist (max 5); exclusive with excluded
excluded_domains	string?	Web-search denylist (max 5)
allowed_x_handles	string?	Comma-separated X handle allowlist (max 20); exclusive with excluded
excluded_x_handles	string?	Comma-separated X handle denylist (max 20)
from_date	string?	Inclusive X search start date (YYYY-MM-DD)
to_date	string?	Inclusive X search end date (YYYY-MM-DD)
enable_image_understanding	bool?	Analyze images on browsed pages and X posts (default on)
enable_video_understanding	bool?	Analyze videos in X posts (default off)
images	string?	Your image input(s): URL / data:image/...;base64,... / local path (max 5)
image_detail	string?	low / high / auto (default high)
system_prompt	string?	Optional system instruction
reasoning_effort	string?	Thinking length for reasoning models: low / medium / high (default high)

images are sent as Responses API input_image parts (local files are base64-encoded, ~20MB max each). This is not “search the web for stock images.”

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Response Shape

Success:

{
  "ok": true,
  "query": "What is xAI?",
  "text": "...",
  "citations": ["https://x.ai"]
}

Failure:

{
  "ok": false,
  "error": "Grok API error (401): ...",
  "status_code": 401
}

Intentionally not returned: full 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).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Development

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp
uv sync
uv run pytest

Project layout:

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Roadmap

• [x] Single lean web_search MCP tool
• [x] Enable upstream web_search and x_search by default
• [x] X handle/date filters and image/video understanding
• [x] Custom base_url / proxy support
• [x] Domain allow/deny filters
• [x] Optional multimodal image input
• [x] Install / run from GitHub via uvx
• [ ] Optional Streamable HTTP transport docs/examples
• [ ] Golden-set evaluation harness for search quality

See the open issues.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

License

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Acknowledgments

• Best-README-Template
• xAI Web Search
• xAI X Search
• Model Context Protocol
• FastMCP
• uv

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES --> [python-shield]: https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white [python-url]: https://www.python.org/ [license-shield]: https://img.shields.io/badge/License-MIT-green?style=for-the-badge [license-url]: ./LICENSE [mcp-shield]: https://img.shields.io/badge/MCP-Server-purple?style=for-the-badge [mcp-url]: https://modelcontextprotocol.io/ [xai-shield]: https://img.shields.io/badge/xAI-Grok-black?style=for-the-badge [xai-url]: https://docs.x.ai/ [xai-web-search-url]: https://docs.x.ai/developers/tools/web-search [fastmcp-shield]: https://img.shields.io/badge/FastMCP-3.x-orange?style=for-the-badge [fastmcp-url]: https://gofastmcp.com/ [httpx-shield]: https://img.shields.io/badge/httpx-async-teal?style=for-the-badge [httpx-url]: https://www.python-httpx.org/ [uv-shield]: https://img.shields.io/badge/uv-package%20manager-DE5FE9?style=for-the-badge [uv-url]: https://docs.astral.sh/uv/ [github-shield]: https://img.shields.io/badge/GitHub-NakanoSanku-181717?style=for-the-badge&logo=github [github-url]: https://github.com/NakanoSanku/grok-web-search-mcp