tradingview-mcp 1.0.0__py3-none-any.whl

tradingview_mcp/utils.py

@@ -0,0 +1,382 @@
+"""
+Utility functions for TradingView MCP.
+
+Provides helper functions for data processing, validation, and technical analysis.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from tradingview_mcp.constants import (
+    ALLOWED_TIMEFRAMES,
+    EXCHANGE_SCREENER,
+    MARKETS,
+    TIMEFRAME_MAP,
+)
+
+
+def sanitize_timeframe(tf: str | None, default: str = "15m") -> str:
+    """
+    Validate and sanitize a timeframe string.
+
+    Args:
+        tf: Timeframe to validate
+        default: Default value if invalid
+
+    Returns:
+        Valid timeframe string
+    """
+    if not tf:
+        return default
+    tf = tf.strip()
+    return tf if tf in ALLOWED_TIMEFRAMES else default
+
+
+def sanitize_exchange(ex: str | None, default: str = "america") -> str:
+    """
+    Validate and sanitize an exchange name.
+
+    Args:
+        ex: Exchange to validate
+        default: Default value if invalid
+
+    Returns:
+        Valid exchange/market string
+    """
+    if not ex:
+        return default
+    ex = ex.strip().lower()
+    if ex in EXCHANGE_SCREENER:
+        return ex
+    if ex in MARKETS:
+        return ex
+    return default
+
+
+def sanitize_market(market: str | None, default: str = "america") -> str:
+    """
+    Validate and sanitize a market name.
+
+    Args:
+        market: Market to validate
+        default: Default value if invalid
+
+    Returns:
+        Valid market string
+    """
+    if not market:
+        return default
+    market = market.strip().lower()
+    return market if market in MARKETS else default
+
+
+def timeframe_to_resolution(tf: str) -> str:
+    """
+    Convert timeframe to TradingView API resolution.
+
+    Args:
+        tf: Timeframe string (e.g., '15m', '1h', '4h', '1D')
+
+    Returns:
+        TradingView resolution string
+    """
+    return TIMEFRAME_MAP.get(tf, tf)
+
+
+def get_screener_for_exchange(exchange: str) -> str:
+    """
+    Get the screener market for an exchange.
+
+    Args:
+        exchange: Exchange name (e.g., 'binance', 'nasdaq')
+
+    Returns:
+        Screener market (e.g., 'crypto', 'america')
+    """
+    return EXCHANGE_SCREENER.get(exchange.lower(), "america")
+
+
+def format_technical_rating(rating: float) -> str:
+    """
+    Convert numeric technical rating to human-readable format.
+
+    Args:
+        rating: Rating value (-1 to 1)
+
+    Returns:
+        Rating label (Strong Buy, Buy, Neutral, Sell, Strong Sell)
+    """
+    if rating >= 0.5:
+        return "Strong Buy"
+    elif rating >= 0.1:
+        return "Buy"
+    elif rating >= -0.1:
+        return "Neutral"
+    elif rating >= -0.5:
+        return "Sell"
+    else:
+        return "Strong Sell"
+
+
+def compute_percent_change(open_price: float, close_price: float) -> float:
+    """
+    Calculate percentage change.
+
+    Args:
+        open_price: Starting price
+        close_price: Ending price
+
+    Returns:
+        Percentage change
+    """
+    if not open_price or open_price == 0:
+        return 0.0
+    return ((close_price - open_price) / open_price) * 100
+
+
+def compute_bollinger_band_width(sma: float, bb_upper: float, bb_lower: float) -> Optional[float]:
+    """
+    Calculate Bollinger Band Width (BBW).
+
+    BBW = (Upper Band - Lower Band) / SMA20
+
+    Args:
+        sma: SMA20 (middle band)
+        bb_upper: Upper Bollinger Band
+        bb_lower: Lower Bollinger Band
+
+    Returns:
+        BBW value or None if calculation fails
+    """
+    if not sma or sma == 0:
+        return None
+    try:
+        return (bb_upper - bb_lower) / sma
+    except (TypeError, ZeroDivisionError):
+        return None
+
+
+def compute_bollinger_rating(
+    close: float, bb_upper: float, bb_middle: float, bb_lower: float
+) -> tuple[int, str]:
+    """
+    Calculate Bollinger Band position rating and signal.
+
+    Rating scale:
+    - +3: Price above upper band (Strong overbought)
+    - +2: Price in upper half above middle (Overbought)
+    - +1: Price slightly above middle (Weak bullish)
+    - -1: Price slightly below middle (Weak bearish)
+    - -2: Price in lower half below middle (Oversold)
+    - -3: Price below lower band (Strong oversold)
+
+    Args:
+        close: Current price
+        bb_upper: Upper band
+        bb_middle: Middle band (SMA20)
+        bb_lower: Lower band
+
+    Returns:
+        Tuple of (rating, signal)
+    """
+    rating = 0
+    signal = "NEUTRAL"
+
+    if close > bb_upper:
+        rating = 3
+        signal = "STRONG_OVERBOUGHT"
+    elif close > bb_middle + ((bb_upper - bb_middle) / 2):
+        rating = 2
+        signal = "BUY"
+    elif close > bb_middle:
+        rating = 1
+        signal = "WEAK_BUY"
+    elif close < bb_lower:
+        rating = -3
+        signal = "STRONG_OVERSOLD"
+    elif close < bb_middle - ((bb_middle - bb_lower) / 2):
+        rating = -2
+        signal = "SELL"
+    elif close < bb_middle:
+        rating = -1
+        signal = "WEAK_SELL"
+
+    return rating, signal
+
+
+def compute_rsi_signal(rsi: float) -> str:
+    """
+    Determine RSI signal.
+
+    Args:
+        rsi: RSI value (0-100)
+
+    Returns:
+        Signal string
+    """
+    if rsi >= 80:
+        return "EXTREMELY_OVERBOUGHT"
+    elif rsi >= 70:
+        return "OVERBOUGHT"
+    elif rsi >= 60:
+        return "BULLISH"
+    elif rsi <= 20:
+        return "EXTREMELY_OVERSOLD"
+    elif rsi <= 30:
+        return "OVERSOLD"
+    elif rsi <= 40:
+        return "BEARISH"
+    else:
+        return "NEUTRAL"
+
+
+def compute_macd_signal(macd: float, signal: float) -> str:
+    """
+    Determine MACD signal.
+
+    Args:
+        macd: MACD line value
+        signal: Signal line value
+
+    Returns:
+        Signal string
+    """
+    diff = macd - signal
+    if diff > 0:
+        if macd > 0:
+            return "STRONG_BULLISH"
+        return "BULLISH"
+    elif diff < 0:
+        if macd < 0:
+            return "STRONG_BEARISH"
+        return "BEARISH"
+    return "NEUTRAL"
+
+
+def analyze_indicators(indicators: dict[str, Any]) -> dict[str, Any]:
+    """
+    Perform comprehensive technical analysis on indicator data.
+
+    Args:
+        indicators: Dictionary of indicator values
+
+    Returns:
+        Analysis results with signals and ratings
+    """
+    result: dict[str, Any] = {"signals": [], "rating": 0, "recommendation": "NEUTRAL"}
+
+    # Extract values
+    close = indicators.get("close", 0)
+    open_price = indicators.get("open", 0)
+    high = indicators.get("high", 0)
+    low = indicators.get("low", 0)
+    volume = indicators.get("volume", 0)
+    rsi = indicators.get("RSI", 50)
+    macd = indicators.get("MACD.macd", 0)
+    macd_signal = indicators.get("MACD.signal", 0)
+    bb_upper = indicators.get("BB.upper", 0)
+    bb_lower = indicators.get("BB.lower", 0)
+    sma20 = indicators.get("SMA20", close)
+    ema50 = indicators.get("EMA50", close)
+    ema200 = indicators.get("EMA200", close)
+    adx = indicators.get("ADX", 0)
+
+    # Price change
+    if open_price and close:
+        change = compute_percent_change(open_price, close)
+        result["change_percent"] = round(change, 2)
+
+    # RSI Analysis
+    if rsi:
+        rsi_signal = compute_rsi_signal(rsi)
+        result["rsi_signal"] = rsi_signal
+        if "OVERBOUGHT" in rsi_signal:
+            result["signals"].append(f"RSI Overbought ({rsi:.1f})")
+            result["rating"] -= 1
+        elif "OVERSOLD" in rsi_signal:
+            result["signals"].append(f"RSI Oversold ({rsi:.1f})")
+            result["rating"] += 1
+
+    # MACD Analysis
+    if macd and macd_signal:
+        macd_sig = compute_macd_signal(macd, macd_signal)
+        result["macd_signal"] = macd_sig
+        if "BULLISH" in macd_sig:
+            result["signals"].append(f"MACD Bullish")
+            result["rating"] += 1
+        elif "BEARISH" in macd_sig:
+            result["signals"].append(f"MACD Bearish")
+            result["rating"] -= 1
+
+    # Bollinger Band Analysis
+    if bb_upper and bb_lower and sma20 and close:
+        bb_rating, bb_signal = compute_bollinger_rating(close, bb_upper, sma20, bb_lower)
+        bbw = compute_bollinger_band_width(sma20, bb_upper, bb_lower)
+        result["bb_rating"] = bb_rating
+        result["bb_signal"] = bb_signal
+        result["bbw"] = round(bbw, 4) if bbw else None
+
+        if bb_rating >= 2:
+            result["signals"].append("Price near/above upper BB")
+            result["rating"] -= 1
+        elif bb_rating <= -2:
+            result["signals"].append("Price near/below lower BB")
+            result["rating"] += 1
+
+        if bbw and bbw < 0.02:
+            result["signals"].append("BB Squeeze (low volatility)")
+
+    # Moving Average Analysis
+    if close and sma20 and ema50 and ema200:
+        if close > sma20 > ema50 > ema200:
+            result["signals"].append("Strong uptrend (above all MAs)")
+            result["rating"] += 2
+        elif close < sma20 < ema50 < ema200:
+            result["signals"].append("Strong downtrend (below all MAs)")
+            result["rating"] -= 2
+        elif close > ema200:
+            result["signals"].append("Above EMA200 (long-term bullish)")
+            result["rating"] += 1
+        elif close < ema200:
+            result["signals"].append("Below EMA200 (long-term bearish)")
+            result["rating"] -= 1
+
+    # ADX Trend Strength
+    if adx:
+        if adx > 50:
+            result["signals"].append(f"Very strong trend (ADX: {adx:.1f})")
+        elif adx > 25:
+            result["signals"].append(f"Trending market (ADX: {adx:.1f})")
+        else:
+            result["signals"].append(f"Ranging/weak trend (ADX: {adx:.1f})")
+
+    # Final recommendation
+    if result["rating"] >= 3:
+        result["recommendation"] = "STRONG_BUY"
+    elif result["rating"] >= 1:
+        result["recommendation"] = "BUY"
+    elif result["rating"] <= -3:
+        result["recommendation"] = "STRONG_SELL"
+    elif result["rating"] <= -1:
+        result["recommendation"] = "SELL"
+    else:
+        result["recommendation"] = "NEUTRAL"
+
+    return result
+
+
+def format_symbol(symbol: str, exchange: str) -> str:
+    """
+    Format a symbol with exchange prefix if needed.
+
+    Args:
+        symbol: Symbol (e.g., 'BTCUSDT' or 'BINANCE:BTCUSDT')
+        exchange: Exchange name
+
+    Returns:
+        Formatted symbol (e.g., 'BINANCE:BTCUSDT')
+    """
+    if ":" in symbol:
+        return symbol.upper()
+    return f"{exchange.upper()}:{symbol.upper()}"

tradingview_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: tradingview-mcp
+Version: 1.0.0
+Summary: A comprehensive MCP server for TradingView market screening with integrated screener functionality
+Author: TradingView MCP Team
+License: MIT
+License-File: LICENSE
+Keywords: crypto,mcp,screener,stocks,technical-analysis,trading,tradingview
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TradingView MCP Server
+
+A comprehensive Model Context Protocol (MCP) server for TradingView market screening with fully integrated screener functionality. This server provides powerful tools for cryptocurrency and stock market analysis directly through the MCP interface.
+
+## Features
+
+### Core Screener Functionality
+- **Direct TradingView API Integration**: Query the TradingView scanner API without external dependencies
+- **Multi-Market Support**: 76+ markets including crypto, stocks, forex, futures, and bonds
+- **SQL-like Query Interface**: Build complex queries with filtering, sorting, and pagination
+- **250+ Technical Indicators**: Access a comprehensive set of technical analysis columns
+
+### MCP Tools
+- `screen_market`: Execute custom market screening queries
+- `get_top_gainers`: Find top gaining assets in any market
+- `get_top_losers`: Find top losing assets in any market
+- `get_premarket_movers`: Pre-market gainers, losers, and most active
+- `get_postmarket_movers`: Post-market activity analysis
+- `get_technical_analysis`: Detailed technical analysis for specific symbols
+- `scan_bollinger_bands`: Bollinger Band squeeze detection
+- `scan_volume_breakout`: Volume breakout detection
+- `scan_rsi_extremes`: RSI overbought/oversold scanner
+- `scan_macd_crossover`: MACD crossover detection
+- `get_all_symbols`: Retrieve all symbols for a market
+- `advanced_query`: Execute advanced queries with AND/OR logic
+
+### MCP Resources
+- `markets://list`: List all available markets
+- `columns://list`: List all available technical indicator columns
+- `exchanges://crypto`: List cryptocurrency exchanges
+- `presets://list`: List predefined screening presets
+
+## Installation
+
+### Using uv (Recommended)
+```bash
+uv add tradingview-mcp
+```
+
+### Using pip
+```bash
+pip install tradingview-mcp
+```
+
+### From Source
+```bash
+git clone https://github.com/your-repo/tradingview-mcp.git
+cd tradingview-mcp
+uv sync
+```
+
+## Usage
+
+### Running the MCP Server
+
+#### Stdio Transport (Default)
+```bash
+tradingview-mcp
+```
+
+#### HTTP Transport
+```bash
+tradingview-mcp streamable-http --host 127.0.0.1 --port 8000
+```
+
+### MCP Client Configuration
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "tradingview-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Example Queries
+
+#### Basic Market Screening
+```python
+# Get top 50 stocks by trading volume
+await client.call_tool("screen_market", {
+    "market": "america",
+    "columns": ["name", "close", "volume", "change"],
+    "sort_by": "volume",
+    "ascending": False,
+    "limit": 50
+})
+```
+
+#### Technical Analysis Screening
+```python
+# Find stocks with RSI below 30 (oversold)
+await client.call_tool("scan_rsi_extremes", {
+    "market": "america",
+    "condition": "oversold",
+    "threshold": 30,
+    "limit": 20
+})
+```
+
+#### Cryptocurrency Screening
+```python
+# Get top crypto gainers
+await client.call_tool("get_top_gainers", {
+    "market": "crypto",
+    "limit": 25
+})
+```
+
+## API Reference
+
+### Markets
+The following markets are supported:
+- **Crypto**: `crypto`, `coin`
+- **Traditional Finance**: `america`, `uk`, `germany`, `japan`, etc. (67 countries)
+- **Other**: `forex`, `futures`, `bonds`, `cfd`, `options`
+
+### Technical Indicators
+Common indicators include:
+- Price: `open`, `high`, `low`, `close`, `volume`
+- Moving Averages: `SMA5`, `SMA10`, `SMA20`, `SMA50`, `SMA100`, `SMA200`, `EMA5`, `EMA10`, `EMA20`, `EMA50`, `EMA100`, `EMA200`
+- Oscillators: `RSI`, `RSI7`, `MACD.macd`, `MACD.signal`, `Stoch.K`, `Stoch.D`
+- Bollinger Bands: `BB.upper`, `BB.lower`
+- Others: `VWAP`, `ATR`, `ADX`, `CCI20`, etc.
+
+See `columns://list` resource for the complete list.
+
+## Development
+
+### Running Tests
+```bash
+uv run pytest tests/
+```
+
+### Code Formatting
+```bash
+uv run ruff format .
+uv run ruff check . --fix
+```
+
+### Type Checking
+```bash
+uv run pyright
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

tradingview_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tradingview_mcp/__init__.py,sha256=V7RLq22Qp1rsMhDYNlXfWkiNaXlo7s4KkNUmSvbGKIM,455
+tradingview_mcp/column.py,sha256=MC7lWksmyaYF4SkVm97Apr8httwip-N-4aVTSyS0CQo,8871
+tradingview_mcp/constants.py,sha256=yGzC9Zie825JqqHKGWukTz4HicGKn0pDiUn8op_Me2Y,12749
+tradingview_mcp/models.py,sha256=CHSQ46A2ljhvzI6YP8XRItUdoDJw1yYebiBANt9xeD0,3366
+tradingview_mcp/query.py,sha256=gkC4t-2_jtuUK3KgzU62wrIcGoaOmY--1EwAshGQb0Q,10871
+tradingview_mcp/scanner.py,sha256=CA8GP-N8uCYacpuUzll9IfalKK0hEUSU9ViVEAO8mwU,7535
+tradingview_mcp/server.py,sha256=xOZ0Vm_RicRVMCyq6y0DKUPpE5gUtAVrERdItmHLdUs,40516
+tradingview_mcp/utils.py,sha256=6O89qIaZ_eYoN3m12r2q4-D8VpJajP5WuwKQbj4ZVHo,10238
+tradingview_mcp-1.0.0.dist-info/METADATA,sha256=vfzUAYJaI5uIz1tPVq1zmjiaU1zK1nAZlhoRLDldk_o,5097
+tradingview_mcp-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tradingview_mcp-1.0.0.dist-info/entry_points.txt,sha256=GZxjGqgVbUlWDp5OzFQoCN_g1UBLyOmfVqCR5uzscnU,57
+tradingview_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=ma04jhucIafnA2IaYn--PlxmCUpqhESjKAu4d0c_Ib4,1141
+tradingview_mcp-1.0.0.dist-info/RECORD,,

tradingview_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tradingview_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tradingview-mcp = tradingview_mcp:main

tradingview_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2022 Shneor Elmaleh
+Copyright (c) 2025 Ahmet Taner Atila
+Copyright (c) 2026 Henrik (k73a)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.