gexbot-mcp

Un servidor MCP ligero que envuelve la API de GEXBot para poder añadirlo como conector personalizado en claude.ai.

Construido con el SDK oficial de MCP para Python (FastMCP), servido sobre HTTP Streamable para poder alojarse de forma remota (p. ej. en Render).

Referencia de especificación: nfa-llc/gexbot-openapi — URL base https://api.gex.bot/v2, autenticación con token Bearer.

Herramientas expuestas

Además, un endpoint HTTP simple GET /health (no es una herramienta MCP) para comprobaciones de disponibilidad / health checks de Render.

Acerca de dte

GEXBot no acepta un entero DTE arbitrario — agrupa los datos en categorías fijas. Este servidor mapea el argumento dte a esas categorías:

• dte=0 → zero (próximo vencimiento / 0DTE)

• dte=1 → one (próximo vencimiento + 1)

• cualquier otro valor → full (agregación completa de todos los vencimientos publicados, hasta ~90 días)

Tickers que te interesan

Sin restricción fija — cualquier ticker que GEXBot soporte funciona (ver list_tickers()). Los que probablemente usarás más: QQQ, SPY, NDX, SPX, SPXW.

Related MCP server: ai-trader

Autenticación

El servidor lee GEXBOT_API_KEY del entorno en el momento de la solicitud y la envía como Authorization: Bearer <key> a GEXBot. La clave nunca está hardcodeada — debe establecerse como variable de entorno dondequiera que lo ejecutes (localmente, en Docker o en Render).

Ejecutar localmente

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

El servidor escucha en http://0.0.0.0:8000 por defecto (se puede sobrescribir con PORT). El endpoint MCP está en /mcp; el health check en /health.

Comprobación rápida:

curl http://localhost:8000/health

Ejecutar con Docker

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

Desplegar en Render (plan gratuito)

1. Sube esta carpeta a un repositorio de GitHub (o GitLab).

2. En el panel de Render: Nuevo + → Web Service → conecta tu repositorio.

   • Render detectará automáticamente el Dockerfile. Deja los comandos de build/start en blanco (Docker se encarga).

   • O, si prefieres una configuración de un clic, este repositorio incluye render.yaml — usa Nuevo + → Blueprint y apunta al repositorio.

3. Establece el Tipo de instancia en Gratis.

4. En Entorno, añade:

   • GEXBOT_API_KEY = tu clave (márcala como Secreto). Pégala tú mismo en el panel de Render — no la pongas en el repositorio ni en render.yaml.

5. Ruta de health check: /health.

6. Despliega. Render construirá la imagen Docker y te dará una URL como: https://gexbot-mcp.onrender.com

Nota: los servicios web gratuitos de Render se apagan después de 15 minutos de inactividad y tardan ~30-60s en despertarse en la siguiente solicitud — la primera llamada a una herramienta después de un período de inactividad puede ser lenta.

Añadir a claude.ai como conector personalizado

1. En claude.ai: Configuración → Conectores → Añadir conector personalizado.

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

3. Guarda. Claude descubrirá las tres herramientas (get_gex_levels, get_gex_profile, list_tickers).

Manejo de errores

Todas las herramientas devuelven un dict JSON compacto. En caso de fallo devuelven {"error": "<mensaje>", ...} en lugar de lanzar una excepción, para que el modelo pueda ver y transmitir el problema. Casos manejados:

• Clave API incorrecta o faltante → 401 de GEXBot → mensaje claro de "comprueba GEXBOT_API_KEY".

• La clave no tiene acceso a un recurso → 403 → mensaje claro.

• Ticker no soportado → 404 → mensaje claro.

• Solicitud incorrecta (p. ej. ticker/categoría malformado) → 400 → se muestra el mensaje de error de GEXBot.

• Caída de GEXBot / casos límite de mercado cerrado → 5xx manejado con un mensaje claro; además, get_gex_levels / get_gex_profile incluyen una bandera "stale": true cuando la marca de tiempo de los datos devueltos tiene más de 24 horas, ya que GEXBot no tiene un error explícito de "mercado cerrado".

• Errores de red/timeout → mensaje claro, sin fuga de stack trace al cliente.

Estructura del proyecto

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