trading-tooltip-mcp

# Trading Toolkit MCP A Model Context Protocol (MCP) server providing 14 real-time market screening and trading intelligence tools. Powered by TradingView's public Screener API — **no API key required, no authentication, no paid subscription, zero cost**. Built for use with [Claude Code](https://claude.ai/claude-code), [Claude Desktop](https://claude.ai), or any MCP-compatible client. ## Tools Overview | Category | Tool | Description | |----------|------|-------------| | **Brief** | `morning_brief` | Full pre-market brief for any list of stocks | | **Brief** | `watchlist_brief` | Load a JSON/CSV watchlist file and brief all symbols | | **Overview** | `market_pulse` | One-call market overview: indices, A/D ratio, top RVOL | | **Overview** | `sector_heatmap` | Sector-level aggregated change, RVOL, leaders/laggards | | **Movers** | `show_movers` | Top US stocks by RVOL, volume, premarket, or gap | | **Movers** | `show_movers_il` | Top Israeli (TASE) stocks by RVOL, volume, or change | | **Movers** | `screener` | Custom screener query with flexible filters | | **Scanner** | `premarket_scanner` | Stocks with premkt volume >= X% of avg daily | | **Scanner** | `gap_scanner` | Stocks gapping up/down by configurable % range | | **Scanner** | `unusual_activity` | High RVOL + small price change (stealth positioning) | | **Scanner** | `earnings_movers` | High RVOL + large price change (catalyst reactions) | | **Analysis** | `compare_stocks` | Side-by-side comparison table for 2-10 stocks | | **Analysis** | `alert_levels` | Key technical levels: MAs, BBands, pivots, ATR | | **Analysis** | `historical_rvol` | Current RVOL context with volume assessment | --- ## Installation ### Prerequisites - Node.js 18+ (tested on Node 25) - An MCP-compatible client (Claude Code, Claude Desktop, etc.) ### Setup ```bash git clone https://github.com/yhaspel/trading-tooltip-mcp.git cd trading-toolkit-mcp npm install ``` ### Configuration **For Claude Code** — add to your project's `.mcp.json`: ```json { "mcpServers": { "trading-toolkit": { "command": "node", "args": ["/path/to/trading-toolkit-mcp/src/server.js"] } } } ``` **For Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "trading-toolkit": { "command": "node", "args": ["/path/to/trading-toolkit-mcp/src/server.js"] } } } ``` Restart your MCP client to load the server. --- ## Tool Reference & Usage Examples ### `morning_brief` Full pre-market brief for a list of stocks. Returns price, change, gap, premarket volume (as % of avg daily), RVOL, full technical analysis (RSI, MACD, MAs, BB, ADX, recommendation score), sector, and market cap. ``` morning_brief with symbols="NASDAQ:NVDA,NASDAQ:PLTR,NYSE:TSM,NASDAQ:TSLA" ``` **Tip:** If the TradingView MCP is also running, first call `watchlist_get` to get symbols, then pass them here. --- ### `watchlist_brief` Load a watchlist from a local JSON or CSV file and run a brief on all symbols. ``` watchlist_brief with file_path="/path/to/my_watchlist.json" ``` JSON format: `["NASDAQ:NVDA", "NYSE:TSM", "TASE:ESLT"]` CSV format: one ticker per line. --- ### `market_pulse` One-call market overview. Returns: SPY, QQQ, IWM, DIA status, advance/decline ratio estimate, and top 5 unusual volume stocks. No parameters needed. ``` market_pulse ``` --- ### `sector_heatmap` Sector-level aggregated view: average change %, average RVOL, stock count, top gainer and top loser per sector. ``` sector_heatmap ``` With filters: ``` sector_heatmap with market="america", min_market_cap=10000000000 ``` --- ### `show_movers` Top US stock movers sorted by your choice of metric. By RVOL (default — best for unusual activity): ``` show_movers ``` By premarket volume: ``` show_movers with sort_by="premarket_volume", min_premarket_volume=500000 ``` Biggest losers: ``` show_movers with sort_by="change_down", min_volume=5000000 ``` Gap ups over $10B market cap: ``` show_movers with sort_by="gap_up", min_market_cap=10000000000 ``` Sort options: `rvol`, `volume`, `premarket_volume`, `gap_up`, `gap_down`, `change_up`, `change_down` --- ### `show_movers_il` Top Israeli (TASE) stock movers. ``` show_movers_il ``` High-volume TASE stocks: ``` show_movers_il with sort_by="volume", min_volume=500000 ``` --- ### `screener` Custom screener query with full control over filters and sorting. Tech stocks down big today: ``` screener with sort_by="change", sort_order="asc", min_volume=5000000, min_market_cap=10000000000, max_change=-5 ``` Israel small-caps gaining: ``` screener with market="israel", sort_by="change", sort_order="desc", min_volume=100000, min_change=3 ``` --- ### `premarket_scanner` Find stocks that have already traded a significant percentage of their average daily volume in premarket. The key metric for gap traders. Stocks with 30%+ of daily average done premarket: ``` premarket_scanner ``` Aggressive filter — 50%+ of daily volume already traded: ``` premarket_scanner with min_premkt_pct_of_avg=50, min_market_cap=5000000000 ``` --- ### `gap_scanner` Find all stocks gapping by a configurable percentage range. Pairs with gap trading strategies. All gaps 4-20%: ``` gap_scanner ``` Only gap downs: ``` gap_scanner with direction="down", min_gap_pct=3, max_gap_pct=15 ``` Large-cap gap ups: ``` gap_scanner with direction="up", min_gap_pct=2, min_market_cap=50000000000 ``` --- ### `unusual_activity` Find stocks with high relative volume but small price change — potential stealth accumulation/distribution or options-driven activity. ``` unusual_activity ``` Tighter filter — 3x+ RVOL with less than 1% move: ``` unusual_activity with min_rvol=3.0, max_abs_change=1.0 ``` --- ### `earnings_movers` Find stocks reacting to earnings or major catalysts: high RVOL combined with large price moves. ``` earnings_movers ``` Only mega-cap reactions: ``` earnings_movers with min_rvol=5.0, min_abs_change=10, min_market_cap=50000000000 ``` --- ### `compare_stocks` Side-by-side comparison table for 2-10 stocks. Shows price, change, RVOL, RSI, ADX, TA rating, price vs MAs, market cap, sector, gap, and premarket change. ``` compare_stocks with symbols="NASDAQ:NVDA,NASDAQ:AMD,NYSE:TSM,NASDAQ:AVGO" ``` --- ### `alert_levels` Key technical levels for a single stock: all major MAs (SMA/EMA 20/50/200), Bollinger Bands, monthly pivot points, RSI, ADX, and ATR. Useful for strike selection and stop placement. ``` alert_levels with symbol="NASDAQ:NVDA" ``` --- ### `historical_rvol` Current RVOL context for a stock: today's volume vs 10-day and 30-day averages, relative volume, premarket volume, and a plain-language assessment (normal/elevated/high/extreme). ``` historical_rvol with symbol="NASDAQ:PLTR" ``` --- ## Data Source All data comes from TradingView's public Screener API (`https://scanner.tradingview.com`): - **No API key required** — the endpoint is public - **No authentication** — no login, no cookies, no session tokens - **No cost** — completely free - **~200ms response time** per query - **Real-time data** — reflects current market conditions ## Available Screener Columns | Column | Description | |--------|-------------| | `name` | Ticker symbol | | `description` | Company name | | `close` | Last closing price | | `change` | Daily change % | | `volume` | Current day volume | | `relative_volume_10d_calc` | RVOL (relative to 10-day average) | | `average_volume_10d_calc` | 10-day average volume | | `average_volume_30d_calc` | 30-day average volume | | `premarket_volume` | Premarket volume | | `premarket_change` | Premarket change % | | `gap` | Gap % from previous close | | `market_cap_basic` | Market capitalization | | `sector` | Sector classification | | `Recommend.All` | Overall TA recommendation (-1 to +1) | | `Recommend.MA` | Moving average recommendation | | `Recommend.Other` | Oscillator recommendation | | `RSI` | RSI(14) | | `SMA20`, `SMA50`, `SMA200` | Simple Moving Averages | | `EMA20`, `EMA50`, `EMA200` | Exponential Moving Averages | | `ADX` | Average Directional Index | | `ATR` | Average True Range | | `MACD.macd`, `MACD.signal` | MACD and signal line | | `BB.upper`, `BB.lower` | Bollinger Band levels | | `Pivot.M.Classic.R1`, `S1`, `Middle` | Monthly pivot points | ## Project Structure ``` trading-toolkit-mcp/ ├── .gitignore ├── LICENSE ├── README.md ├── package.json └── src/ ├── server.js # MCP server entry point (14 tools) └── tools/ ├── screener.js # TradingView Screener API wrapper ├── movers.js # show_movers, show_movers_il, screener ├── brief.js # morning_brief ├── scanners.js # premarket_scanner, gap_scanner, unusual_activity, earnings_movers ├── analysis.js # compare_stocks, alert_levels, historical_rvol ├── market.js # sector_heatmap, market_pulse └── watchlist.js # watchlist_brief ``` ## Supported Markets | Market | Endpoint | Coverage | |--------|----------|----------| | US (NYSE, NASDAQ, AMEX) | `/america/scan` | ~8,000+ stocks | | Israel (TASE) | `/israel/scan` | ~600+ stocks | Additional markets can be added by extending the `MARKETS` object in `screener.js`. TradingView's Screener API supports many more markets including Europe, Asia, and crypto. ## Independence This MCP server is **completely standalone**: - Does **NOT** require TradingView Desktop - Does **NOT** require the TradingView MCP - Does **NOT** require any API keys or paid subscriptions - Works alongside other MCP servers (TradingView, MT Newswires, etc.) — Claude orchestrates them together ## Limitations - **No historical data** — the screener returns current/real-time snapshots only - **No news** — use MT Newswires MCP or web search for news - **Premarket data** — available for US stocks only (TASE has no formal premarket) - **Rate limits** — none observed for reasonable usage ## Dependencies - [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — MCP server SDK - [`zod`](https://www.npmjs.com/package/zod) — Schema validation No other dependencies. Uses Node.js built-in `fetch` for HTTP requests. ## License MIT ## Author Yuval Haspel