Petros Trading Scanner MCP

Read-only Model Context Protocol (MCP) server for short-term stock and ETF market research. It helps ChatGPT analyze futures, premarket movers, market breadth, sector strength, earnings, watchlist signals, and daily briefings.

This server does not place trades. Trade execution is handled separately (e.g. Robinhood). It does not store personal data or broker credentials.

Features

Data sources (free/public)

1. Finviz — futures, breadth, snapshot, earnings API

2. Yahoo Finance — batch spark API for quotes/futures; individual chart fallback

3. Nasdaq — quote fallback when Yahoo is rate-limited (price, change %, volume)

4. Finviz snapshot — top gainers/losers/unusual volume/major news as secondary fallback

5. MarketWatch — premarket movers (often blocked on cloud hosts with HTTP 401)

6. Yahoo Finance screeners — day gainers/losers/actives when MarketWatch is blocked

Caching: 5 minutes for market data, 15 minutes for daily briefings.

Watchlist quotes resolve in order: Yahoo batch → Nasdaq → Finviz snapshot → Yahoo individual. Each signal includes quoteSource, price, changePercent, and volume when available.

Note: MarketWatch frequently returns HTTP 401 from Heroku and other cloud servers due to bot protection. The server automatically falls back to Yahoo Finance, then Finviz. To skip MarketWatch entirely, set MARKETWATCH_ENABLED=false in Heroku config vars.

Related MCP server: market-data-mcp

Local development

Prerequisites

• Node.js 20+

• npm

Setup

git clone <your-repo-url>
cd mcp-trading
cp .env.example .env
npm install
npm run dev

Server starts on http://localhost:3000 by default.

• Health: GET /health

• MCP: POST /mcp (Streamable HTTP)

Scripts

Optional API key

Set MCP_SERVER_API_KEY in .env. When set, all /mcp routes require:

Authorization: Bearer <your-key>

Deploy to Heroku

heroku create petros-trading-scanner
heroku config:set MCP_SERVER_API_KEY=your-secret-key
git push heroku main

Heroku sets PORT automatically. The app binds to 0.0.0.0 and uses process.env.PORT.

Verify deployment:

curl https://petros-trading-scanner.herokuapp.com/health

Connect to ChatGPT Developer Mode

1. Deploy the server (Heroku or another HTTPS host).

2. In ChatGPT → Settings → Connectors / Developer Mode, add a custom MCP server.

3. Use your public MCP URL, for example:

   • https://petros-trading-scanner.herokuapp.com/mcp

4. If you configured MCP_SERVER_API_KEY, add the Bearer token in the connector auth settings.

The server implements Streamable HTTP (POST /mcp) compatible with ChatGPT Apps / Developer Mode.

Example prompts

• "Use my Trading Scanner MCP to get today's daily briefing."

• "Check futures and premarket movers."

• "Analyze SOXL based on semiconductor strength."

• "Give me a market bias for today."

• "Run semiconductor strength for my SOXL workflow."

• "Run watchlist signals for SOXL, MU, NVDA, AMD, AVGO, INTC, MRVL, WDC."

• "Review my SOXL position — cost basis $50, current value $51.17."

• "Review my AAPL position — cost basis $180, current value $195."

Example: position review tool input

Works for any stock or ETF (SOXL, NVDA, AAPL, TQQQ, etc.):

{
  "symbol": "SOXL",
  "costBasis": 50,
  "currentValue": 51.17
}

Expected shape (values vary with live market data):

{
  "action": "hold",
  "confidence": 76,
  "thesis": "Semiconductor sector remains strong despite weak futures.",
  "strengths": ["..."],
  "risks": ["..."]
}

Example: daily briefing tool input

{
  "focusSymbols": ["SOXL", "MU", "NVDA", "AMD", "AVGO", "INTC", "MRVL", "WDC"],
  "portfolioContext": "Holding SOXL from starter account",
  "positions": [
    {
      "symbol": "SOXL",
      "costBasis": 50,
      "currentValue": 51.17
    }
  ]
}

The briefing now includes:

• sources.futuresSource, sources.premarketSource, sources.breadthSource, etc.

• confidence (0–100) alongside marketBias

• news[] with impact (high | medium | low) and sentiment

• portfolioNotes[] with thesis status per position

• semiconductorStrength summary block

Scoring (transparent, not advice)

Market bias uses:

• Nasdaq 100 futures ±0.5%

• S&P 500 futures ±0.3%

• Advancing/declining breadth above 55%

Confidence (0–100) increases as the bias score moves away from neutral and more signals agree. Example: marketBias: "bearish" with confidence: 72 = moderately-to-strongly bearish, not a mild lean.

Semiconductor strength tracks NVDA, AMD, MU, AVGO, INTC, MRVL, WDC, TSM, AMAT, LRCX, SMCI. Strong if 5+ are positive premarket or in major news.

SOXL scoring considers semiconductor strength + Nasdaq futures direction. Leveraged ETF risk flags are always included.

Quote verification

Watchlist signals and semiconductor strength include extra fields so you can sanity-check prices:

Parser note: Nasdaq quotes use primaryData.lastSalePrice — not market cap, 52-week high, or volume. If a price looks wrong, check previousClose and asOf: when change % looks realistic but the level seems off, the upstream feed (Yahoo/Nasdaq) may be reporting a different session or a forward-dated close. Cross-check with your broker.

Daily briefings also include top-level dataFreshness — "fresh" only when futures, premarket, breadth, and all watchlist quotes are within the freshness window.

get_watchlist_signals returns an overall confidence (average of per-symbol quote confidence scores) and quoteDiagnostics showing Yahoo batch success vs fallback paths.

The tools return data, scores, and reasons only — not buy/sell recommendations. ChatGPT interprets the output; you make your own decisions.

Project structure

src/
  index.ts
  server.ts
  mcp/
    tools.ts
    schemas.ts
  services/
    finviz.ts
    marketwatch.ts
    yahoo.ts
    scoring.ts
    marketData.ts
    cache.ts
    http.ts
  types/
    market.ts
  utils/
    parseNumber.ts
    logger.ts
    quoteValidation.ts
    newsAnalysis.ts
    dataFreshness.ts
    quoteConfidence.ts

Disclaimer

Development note: This is a research assistant only. It does not provide financial advice and does not place trades. Market data may be delayed or incomplete. Always verify quotes and consult your own judgment before trading.