Achmad
c48e188b81
Document the new from_date/to_date parameters, supported date formats, resolution options, and usage examples including intraday time windows.
143 lines
4.3 KiB
Markdown
143 lines
4.3 KiB
Markdown
# 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/
|
|
```
|