# TradingView Screener MCP Server

MCP server that wraps the [tradingview-screener](https://github.com/shner-elmo/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:

```python
# 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:
```json
{"field": "RSI", "operator": ">", "value": 70}
```

Nested group:
```json
{"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

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

## Run

```bash
# 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

```bash
pytest tests/
```