tradingview-screener-mcp/README.md

TradingView Screener MCP Server

MCP server that wraps the tradingview-screener library as granular MCP tools for stock screening, technical analysis, and market data retrieval.

Tools

Quotes & Screening

Tool	Description
get_stock_quotes	Get quote data for specific tickers
screen_market	General-purpose screener with filters, sorting, pagination
find_top_gainers	Top gainers by percent change
find_top_losers	Top losers by percent change
find_most_active	Most active by volume
technical_scan	Screen by technical indicator conditions
fundamental_scan	Screen by fundamental metrics

Historical Candles

Tool	Description
get_historical_candles	Fetch OHLCV candlestick data with pattern detection

Supports count-based and date/time range queries:

# Last 30 daily candles
get_historical_candles("NASDAQ:AAPL")

# Specific date range (daily)
get_historical_candles("IDX:BBRI", from_date="2026-05-08", to_date="2026-05-13")

# Intraday — hourly candles for a date range
get_historical_candles("IDX:BBRI", resolution="60", from_date="2026-05-08", to_date="2026-05-13")

# Intraday — 1-minute candles for a specific time window
get_historical_candles("NASDAQ:AAPL", resolution="1", from_date="2026-05-17 14:00", to_date="2026-05-17 14:05")

Resolutions: 1, 5, 15, 30, 60, 240 (minutes), D (daily, default), W (weekly), M (monthly)

Date formats: YYYY-MM-DD, YYYY-MM-DD HH:MM, or YYYY-MM-DD HH:MM:SS (all UTC). When only from_date is given, to_date defaults to now. Date-only to_date is inclusive (covers the full day through 23:59:59).

Utilities

Tool	Description
list_markets	List available market types and stock countries
list_fields	List screener fields by category
set_session	Store TradingView session ID in memory
clear_session	Clear stored session ID

Filter Conditions

Simple condition:

{"field": "RSI", "operator": ">", "value": 70}

Nested group:

{"operator": "or", "filters": [
  {"field": "RSI", "operator": ">", "value": 70},
  {"field": "RSI", "operator": "<", "value": 30}
]}

Supported Operators

Operator	Aliases	Description
>	greater	Greater than
>=	egreater	Greater or equal
<	less	Less than
<=	eless	Less or equal
==	equal	Equal
!=	nequal	Not equal
between		Value between [lo, hi]
not_between		Value not between [lo, hi]
isin		Value in list
not_in		Value not in list
has		String contains
has_none_of		String contains none of
like		Pattern match
not_like		Pattern not match
empty		Field is empty
not_empty		Field is not empty
crosses		Crosses another field
crosses_above		Crosses above another field
crosses_below		Crosses below another field
above_pct		Above field by % multiplier
below_pct		Below field by % multiplier
between_pct		Between % of field
in_day_range		In 1-day range [lo, hi]
in_week_range		In 1-week range [lo, hi]
in_month_range		In 1-month range [lo, hi]

Market Types

• stocks (default) — use market_country for country (e.g. "america", "india")
• crypto, crypto_dex, coin — cryptocurrency markets
• forex — currency pairs
• futures, bond, cfd — derivative markets
• options — use market_country for underlying symbol

Session ID

TradingView session cookies enable real-time data. Priority:

1. Per-call sessionid parameter
2. set_session tool (in-memory)
3. TV_SESSION_ID environment variable (loaded from .env via python-dotenv)

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install .
cp .env.example .env
# Edit .env with your TV_SESSION_ID

Run

# STDIO transport (default — for Claude Desktop, NanoClaw, etc.)
python server.py

# Streamable HTTP transport
python server.py --transport streamable-http --host 0.0.0.0 --port 8000

# SSE transport
python server.py --transport sse --host 127.0.0.1 --port 8000

Tests

pytest tests/