grok-web-search-mcp

Язык: English | 中文

О проекте

Агентам нужен живой доступ к вебу и X с цитатами, а не просто завершение чата. Этот проект оборачивает серверные инструменты xAI web_search и x_search в единый MCP-инструмент, поэтому такие хосты, как Grok, Cursor или Claude Desktop, могут вызывать их без встраивания клиентской логики xAI.

Репозиторий: https://github.com/NakanoSanku/grok-web-search-mcp

Вызов вышестоящего API (упрощённо):

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
    }
  ]
}

Цели дизайна:

• Один MCP-инструмент, один контракт вызова — модели могут передавать только query / scope / recency / images

• Компактные результаты — query / text / citations / sources_used (без сырого дампа вышестоящего API)

• Настраиваемый base URL — официальный https://api.x.ai/v1 или OpenAI-совместимые прокси

• Опциональный ввод изображений — прикрепляйте https-URL или data URI (локальные пути — по желанию)

• PyPI не требуется — запуск прямо из GitHub через uvx --from git+...

Возможности

Не включено: enable_image_search (встраивание веб-галереи изображений). Используйте images, когда изображение предоставляете вы; используйте enable_image_understanding для изображений на просматриваемых страницах и в постах X.

Создано с помощью

Related MCP server: WebQuest MCP

Начало работы

Предварительные требования

• Python 3.10+

• Ключ xAI API (или ключ для совместимого шлюза)

• uv (рекомендуется для uvx из GitHub)

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

Быстрый старт (uvx из GitHub)

Для повседневного использования MCP локальный клон не требуется:

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

Зафиксируйте ветку, тег или коммит, когда нужна воспроизводимость:

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

Локальная установка для разработки

1. Клонируйте репозиторий:

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

2. Установите зависимости:

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

3. Создайте локальный файл окружения:

   cp .env.example .env

4. Отредактируйте .env и укажите как минимум GROK_API_KEY (см. Конфигурация).

Конфигурация

Не храните секреты в git. По возможности используйте переменные окружения, внедряемые хостом, для MCP-конфигураций.

Использование

Запуск сервера

Рекомендуемый способ (из GitHub):

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

Из локальной копии:

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

Пример совместимого прокси:

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-хоста

Предпочтительно: запуск из GitHub через uvx (без локального пути).

Хосты в JSON-стиле (Cursor / Claude Desktop и т.д.):

{
  "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 (~/.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"

Зафиксируйте ref (ветку / тег / коммит):

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

Только для локальной разработки (абсолютный путь к копии):

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

Инструмент: web_search

Каждая модель хоста должна использовать один и тот же контракт из четырёх ключей. Дополнительные аргументы (model, reasoning_effort, system_prompt, фильтры доменов/аккаунтов) отклоняются. Параметры качества находятся в переменных окружения, чтобы поведение поиска не различалось между моделями.

Канонический пример:

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

Затем сервер: нормализует query, внедряет фиксированный системный промпт, применяет операторские фильтры из окружения, сопоставляет recency с границами дат X и всегда использует настроенную модель / усилия рассуждений.

images — это части input_image из Responses API. Локальные пути файловой системы отключены по умолчанию. Это не «поиск в вебе стоковых изображений».

Структура ответа

Успех (MCP isError: false, структурированный контент):

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

Сбой — это ошибка инструмента на уровне протокола (isError: true) с коротким сообщением, например Grok API error (401): Invalid API key. Неполные или пустые ответы вышестоящего API также считаются ошибками, а не молчаливым успехом.

Намеренно не возвращаются: API-ключ, model, base_url, сырой JSON вышестоящего API или blob-объекты аннотаций (URL-адреса извлекаются только в citations). Диагностируйте конфигурацию вне результата инструмента (переменные окружения / настройки MCP на хосте / журналы stderr).

Пример Python-клиента

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())

Реальные вызовы расходуют квоту модели и серверного поиска. Модульные тесты используют моки и не обращаются к сети.

Разработка

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

Структура проекта:

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

Дорожная карта

• Один компактный MCP-инструмент web_search

• Включить вышестоящие web_search и x_search по умолчанию

• Фильтры по X-аккаунту/дате и понимание изображений/видео

• Поддержка настраиваемого base_url / прокси

• Фильтры разрешённых/запрещённых доменов

• Опциональный мультимодальный ввод изображений

• Установка / запуск из GitHub через uvx

• Ошибки на уровне протокола, повторные попытки, тайм-ауты/стандартные параметры reasoning

• Локальный jail для изображений (отключён по умолчанию)

• Канонический контракт вызова MCP (query / scope / recency / images)

• Документация/примеры для опционального Streamable HTTP transport

• Оценочный стенд на основе golden-set для качества поиска

См. открытые issues.

Участие в разработке

Вклад приветствуется.

1. Сделайте форк проекта

2. Создайте свою ветку функции (git checkout -b feature/AmazingFeature)

3. Сделайте коммит своих изменений (git commit -m 'Add some AmazingFeature')

4. Запушьте в ветку (git push origin feature/AmazingFeature)

5. Откройте Pull Request

Пожалуйста, сохраняйте набор инструментов компактным: предпочитайте один хорошо документированный инструмент множеству тонких обёрток.

Лицензия

Распространяется под лицензией MIT. Подробнее см. в LICENSE.

Благодарности

• Best-README-Template

• xAI Web Search

• xAI X Search

• Model Context Protocol

• FastMCP

• uv