gexbot-mcp

Тонкий MCP сервер, оборачивающий GEXBot API, чтобы его можно было добавить как пользовательский коннектор в claude.ai.

Создан с использованием официального MCP Python SDK (FastMCP), работает через Streamable HTTP, поэтому его можно размещать удалённо (например, на Render).

Спецификация: nfa-llc/gexbot-openapi — базовый URL https://api.gex.bot/v2, аутентификация по Bearer-токену.

Доступные инструменты

Плюс обычный HTTP-эндпоинт GET /health (не MCP-инструмент) для проверок аптайма / проверок здоровья Render.

О dte

GEXBot не принимает произвольное целое DTE — он группирует данные в фиксированные категории. Этот сервер сопоставляет аргумент dte с этими категориями:

• dte=0 → zero (следующая экспирация / 0DTE)

• dte=1 → one (следующая экспирация + 1)

• любое другое значение → full (полная агрегация по всем опубликованным экспирациям, до ~90 дней)

Тикеры, которые вам нужны

Нет жёстких ограничений — работает любой тикер, поддерживаемый GEXBot (см. list_tickers()). Скорее всего, вы будете чаще всего использовать: QQQ, SPY, NDX, SPX, SPXW.

Related MCP server: ai-trader

Аутентификация

Сервер читает GEXBOT_API_KEY из окружения во время запроса и отправляет его как Authorization: Bearer <key> в GEXBot. Ключ никогда не захардкожен — он должен быть задан как переменная окружения там, где вы запускаете это (локально, в Docker или на Render).

Запуск локально

python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

set GEXBOT_API_KEY=gexbot_custom_your_key_here   # cmd.exe
# or: $env:GEXBOT_API_KEY = "gexbot_custom_your_key_here"   # PowerShell

python server.py

Сервер по умолчанию слушает http://0.0.0.0:8000 (можно переопределить через PORT). MCP-эндпоинт находится на /mcp; проверка здоровья — на /health.

Быстрая проверка:

curl http://localhost:8000/health

Запуск с Docker

docker build -t gexbot-mcp .
docker run -p 8000:8000 -e GEXBOT_API_KEY=gexbot_custom_your_key_here gexbot-mcp

Развёртывание на Render (бесплатный тариф)

1. Запушьте эту папку в репозиторий GitHub (или GitLab).

2. В панели Render: New + → Web Service → подключите ваш репозиторий.

   • Render автоматически определит Dockerfile. Оставьте команды сборки/запуска пустыми (Docker справится).

   • Или, если вы предпочитаете конфигурацию в один клик, этот репозиторий включает render.yaml — используйте New + → Blueprint и укажите на репозиторий.

3. Установите Тип инстанса в Free.

4. В разделе Окружение добавьте:

   • GEXBOT_API_KEY = ваш ключ (отметьте его как Secret). Вставьте его самостоятельно в панели Render — не помещайте его в репозиторий или в render.yaml.

5. Путь проверки здоровья: /health.

6. Разверните. Render соберёт Docker-образ и выдаст вам URL вида: https://gexbot-mcp.onrender.com

Примечание: бесплатные веб-сервисы Render засыпают после 15 минут бездействия и требуют ~30-60 секунд на пробуждение при следующем запросе — первый вызов инструмента после простоя может быть медленным.

Добавление в claude.ai как пользовательского коннектора

1. В claude.ai: Настройки → Коннекторы → Добавить пользовательский коннектор.

2. URL: https://<your-app>.onrender.com/mcp

3. Сохраните. Claude обнаружит три инструмента (get_gex_levels, get_gex_profile, list_tickers).

Обработка ошибок

Все инструменты возвращают компактный JSON-словарь. При сбое они возвращают {"error": "<message>", ...} вместо исключения, чтобы модель могла увидеть и передать проблему. Обрабатываемые случаи:

• Неверный/отсутствующий API-ключ → 401 от GEXBot → понятное сообщение «проверьте GEXBOT_API_KEY».

• Ключу не хватает доступа к ресурсу → 403 → понятное сообщение.

• Неподдерживаемый тикер → 404 → понятное сообщение.

• Неверный запрос (например, некорректный тикер/категория) → 400 → сообщение об ошибке GEXBot отображается.

• Сбой GEXBot / крайние случаи закрытия рынка → 5xx обрабатывается с понятным сообщением; дополнительно get_gex_levels / get_gex_profile включают флаг "stale": true, когда временная метка возвращённых данных старше 24 часов, поскольку сам GEXBot не имеет явной ошибки «рынок закрыт».

• Сетевые ошибки/таймауты → понятное сообщение, без утечки стектрейса клиенту.

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

server.py         # the MCP server (FastMCP, Streamable HTTP)
requirements.txt
Dockerfile
render.yaml        # optional Render Blueprint config
.env.example