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

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

## NanoClaw Integration

Add to your NanoClaw group's `.mcp.json`:

```json
{
  "mcpServers": {
    "tradingview-screener": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/server.py"],
      "env": {
        "TV_SESSION_ID": "${TV_SESSION_ID}"
      }
    }
  }
}
```

For streamable HTTP (server runs externally):

```json
{
  "mcpServers": {
    "tradingview-screener": {
      "url": "http://host.docker.internal:8000/mcp"
    }
  }
}
```

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