Living Screener MCP

Hosted-ready, review-only MCP server for stock, options, crypto-watch, trade planning, risk checks, journaling, postmortems, backtesting, and rule improvement.

This project is designed to work beside Robinhood's official Trading MCP. It does not store Robinhood credentials, does not call Robinhood APIs, and cannot place broker orders.

What Live-Ready Means

Live-ready means hosted, authenticated, persistent, real-time-capable, and ready for an agent workflow.

It does not mean uncontrolled autonomous trading.

Safety Guarantees

• REVIEW_ONLY=true

• PLACE_ORDERS=false

• No order placement tools exist.

• No Robinhood credential tools exist.

• Market orders are blocked.

• Zero-DTE is review/planning only.

• Daily drawdown warnings and lockouts are enforced.

• PASS is always valid and logged.

• Risk checks produce execution intent only, never execution.

Local Setup

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m unittest discover -s tests

Local Codex STDIO MCP:

codex mcp add living-screener -- .\.venv\Scripts\python.exe .\mcp_server.py

Local HTTP server:

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Health check:

http://127.0.0.1:8000/health

MCP endpoint:

http://127.0.0.1:8000/mcp

Hosted Setup

Set:

HOSTED_MODE=true
SCREENER_AUTH_TOKEN=<long random token>
DATABASE_PATH=/app/data/living_screener.sqlite3
REVIEW_ONLY=true
PLACE_ORDERS=false

Deploy with Docker, Render, or Railway. See docs/deployment_guide.md.

Agent Workflow

1. Use Living Screener MCP to scan and rank opportunities.

2. Use Living Screener MCP to generate a trade plan.

3. Use Living Screener MCP to risk-check the trade plan.

4. Use Robinhood Trading MCP separately for quotes, tradability, options chains, and broker order review.

5. Stop for user approval during early testing.

6. If approved, Robinhood MCP handles execution.

7. Living Screener MCP logs the decision and later postmortems the result.

Tests

.\.venv\Scripts\python.exe -m unittest discover -s tests

The suite checks safety gates, storage, logging, backtesting look-ahead protection, and that broker execution is impossible from this MCP.