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를 읽어 GEXBot에 Authorization: Bearer <key>로 전송합니다. 키는 절대 하드코딩되지 않습니다 — 실행하는 모든 곳(로컬, 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. Instance Type을 Free로 설정합니다.

4. Environment에서 다음을 추가합니다:

   • GEXBOT_API_KEY = 당신의 키 (Secret으로 표시). Render 대시보드에서 직접 붙여넣으세요 — 저장소나 render.yaml에 넣지 마세요.

5. Health Check Path: /health.

6. 배포. Render가 Docker 이미지를 빌드하고 다음과 같은 URL을 제공합니다: https://gexbot-mcp.onrender.com

참고: Render의 무료 웹 서비스는 15분 동안 비활성 상태면 종료되고, 다음 요청 시 다시 깨어나는 데 ~30-60초가 걸립니다 — 유휴 시간 후 첫 도구 호출은 느릴 수 있습니다.

claude.ai에 사용자 지정 커넥터로 추가

1. claude.ai에서: Settings → Connectors → Add custom connector.

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

3. 저장. Claude가 세 가지 도구(get_gex_levels, get_gex_profile, list_tickers)를 발견합니다.

오류 처리

모든 도구는 간결한 JSON 사전을 반환합니다. 실패 시 예외를 발생시키는 대신 {"error": "<message>", ...}를 반환하여 모델이 문제를 보고 전달할 수 있습니다. 처리되는 경우:

• 잘못되었거나 누락된 API 키 → GEXBot에서 401 → "GEXBOT_API_KEY 확인" 메시지가 명확하게 표시됩니다.

• 키가 리소스에 대한 액세스 권한이 없음 → 403 → 명확한 메시지.

• 지원되지 않는 티커 → 404 → 명확한 메시지.

• 잘못된 요청(예: 잘못된 티커/카테고리) → 400 → GEXBot의 오류 메시지가 표시됩니다.

• GEXBot 중단 / 시장 마감 경계 사례 → 5xx는 명확한 메시지로 처리됩니다. 또한 get_gex_levels / get_gex_profile는 반환된 데이터의 타임스탬프가 24시간보다 오래된 경우 "stale": true 플래그를 포함합니다. GEXBot 자체에는 명시적인 "시장 마감" 오류가 없기 때문입니다.

• 네트워크/시간 초과 오류 → 명확한 메시지, 클라이언트에 스택 추적이 유출되지 않습니다.

프로젝트 구조

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