tradingview-mcp 1.0.0__tar.gz → 1.0__tar.gz

{tradingview_mcp-1.0.0 → tradingview_mcp-1.0}/LICENSE

@@ -1,7 +1,5 @@
 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

tradingview_mcp-1.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: tradingview-mcp
+Version: 1.0
+Summary: A comprehensive MCP server for TradingView market screening with integrated screener functionality
+Project-URL: Homepage, https://github.com/k73a/tradingview-mcp
+Project-URL: Documentation, https://github.com/k73a/tradingview-mcp#readme
+Project-URL: Repository, https://github.com/k73a/tradingview-mcp
+Project-URL: Issues, https://github.com/k73a/tradingview-mcp/issues
+Project-URL: Changelog, https://github.com/k73a/tradingview-mcp/blob/main/CHANGELOG.md
+Author: TradingView MCP Team
+License: MIT
+License-File: LICENSE
+Keywords: crypto,mcp,model-context-protocol,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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+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-cov>=4.0.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
+
+[![PyPI version](https://badge.fury.io/py/tradingview-mcp.svg)](https://badge.fury.io/py/tradingview-mcp)
+[![Python](https://img.shields.io/pypi/pyversions/tradingview-mcp.svg)](https://pypi.org/project/tradingview-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/k73a/tradingview-mcp/workflows/Test/badge.svg)](https://github.com/k73a/tradingview-mcp/actions)
+
+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.
+
+## Quick Start (No Installation Required)
+
+Use `uvx` to run directly without installing:
+
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+## 🤖 For AI Agents
+
+**📖 Read [AI.md](AI.md) for the complete guide!** You can copy the entire AI.md file to understand all capabilities.
+
+**Quick Start:**
+1. Call `get_help()` to understand how to use this MCP
+2. Call `ai_get_reference()` for markets, columns, and filter references
+
+Key points:
+- All results include `description` field with full names (e.g., "Apple Inc." not just "AAPL")
+- Use `limit` parameter to control result count (default: 25)
+- Use `search_symbols("apple", "america")` to search by company name
+
+```
+# Quick examples:
+get_top_gainers("america", 10)       # Top 10 US stock gainers
+search_symbols("tesla", "america")    # Search for Tesla
+get_symbol_info("NASDAQ:AAPL")       # Apple Inc. details
+```
+
+## 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
+- **AI-Friendly Design**: Includes `description` (full name), token-saving limits, and help tools
+
+### MCP Tools
+
+#### 🔍 Discovery & Help Tools (AI Start Here!)
+- `get_help(topic)`: **📖 Required reading!** Get usage guide and examples
+- `search_symbols(query, market)`: 🔍 Search by company name (e.g., "Apple", "Tesla")
+- `get_symbol_info(symbol)`: Get detailed symbol information
+- `ai_get_reference()`: AI quick reference guide
+
+#### Screening Tools
+- `screen_market`: Execute custom market screening queries
+- `get_top_gainers`: Find top gaining assets (includes full company names)
+- `get_top_losers`: Find top losing assets (includes full company names)
+- `get_most_active`: Most traded by volume
+- `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
+
+#### AI-Friendly Reference Tools
+- `search_available_fields`: Search for fields/columns by name or description
+- `get_field_info`: Get display name and type for a specific field
+- `get_code_example`: Get Python code examples for screener types
+- `list_fields_for_market`: List available fields with pagination
+- `get_common_fields_summary`: Get commonly used fields by category
+- `get_screener_preset`: Retrieve predefined screener presets
+- `get_market_metainfo`: Field definitions and allowed values per market
+
+### 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
+- `docs://params`: Screener params format and schema
+- `docs://screeners`: Predefined screener presets overview
+- `docs://fields`: Field display names (paginated)
+- `docs://markets`: Markets metadata
+- `docs://ai-reference`: AI quick reference guide
+- `docs://code-examples`: Python code examples for screeners
+
+## Installation
+
+### Using uvx (Recommended - No Install)
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+### Using uv
+```bash
+uv add tradingview-mcp
+```
+
+### Using pip
+```bash
+pip install tradingview-mcp
+```
+
+### From Source
+```bash
+git clone https://github.com/k73a/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
+
+#### Using uvx (Recommended)
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+#### Using installed package
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "tradingview-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### For AI Agents: Getting Started
+
+1. **First, call `ai_get_reference()`** to understand available markets, columns, and filters
+2. Use `search_available_fields("your query")` to find specific columns
+3. Use `get_code_example("Stocks (legacy)")` to see query patterns
+4. Build queries using `screen_market()` or `advanced_query()`
+
+### 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
+
+### Setup Development Environment
+```bash
+git clone https://github.com/k73a/tradingview-mcp.git
+cd tradingview-mcp
+uv sync --all-extras
+```
+
+### Running Tests
+```bash
+uv run pytest tests/ -v
+```
+
+### Code Formatting
+```bash
+uv run ruff format .
+uv run ruff check . --fix
+```
+
+### Type Checking
+```bash
+uv run pyright
+```
+
+### Debug Mode
+
+Enable structured debug responses from tools by setting:
+
+```bash
+export TRADINGVIEW_MCP_DEBUG=1
+```
+
+### Docs Data Path (Optional)
+
+If you want the full TradingView Screener docs datasets (e.g., large metainfo files),
+point the loader to your docs data directory:
+
+```bash
+export TRADINGVIEW_SCREENER_DOCS_DATA=/path/to/TradingView-Screener-docs/data
+```
+
+## Publishing & Releases
+
+This project uses GitHub Actions for automated publishing to PyPI:
+
+### Automatic Updates
+- **Weekly auto-update**: Every Monday, the workflow checks for dependency updates, runs tests, and publishes a new version if there are changes
+- **Manual trigger**: You can manually trigger updates from the GitHub Actions tab
+
+### Manual Release
+To create a manual release:
+
+1. Update version in `pyproject.toml`
+2. Commit and create a tag:
+   ```bash
+   git commit -am "Bump version to x.y.z"
+   git tag vx.y.z
+   git push origin main --tags
+   ```
+3. GitHub Actions will automatically build and publish to PyPI
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed release instructions.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

tradingview_mcp-1.0/README.md

@@ -0,0 +1,298 @@
+# TradingView MCP Server
+
+[![PyPI version](https://badge.fury.io/py/tradingview-mcp.svg)](https://badge.fury.io/py/tradingview-mcp)
+[![Python](https://img.shields.io/pypi/pyversions/tradingview-mcp.svg)](https://pypi.org/project/tradingview-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/k73a/tradingview-mcp/workflows/Test/badge.svg)](https://github.com/k73a/tradingview-mcp/actions)
+
+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.
+
+## Quick Start (No Installation Required)
+
+Use `uvx` to run directly without installing:
+
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+## 🤖 For AI Agents
+
+**📖 Read [AI.md](AI.md) for the complete guide!** You can copy the entire AI.md file to understand all capabilities.
+
+**Quick Start:**
+1. Call `get_help()` to understand how to use this MCP
+2. Call `ai_get_reference()` for markets, columns, and filter references
+
+Key points:
+- All results include `description` field with full names (e.g., "Apple Inc." not just "AAPL")
+- Use `limit` parameter to control result count (default: 25)
+- Use `search_symbols("apple", "america")` to search by company name
+
+```
+# Quick examples:
+get_top_gainers("america", 10)       # Top 10 US stock gainers
+search_symbols("tesla", "america")    # Search for Tesla
+get_symbol_info("NASDAQ:AAPL")       # Apple Inc. details
+```
+
+## 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
+- **AI-Friendly Design**: Includes `description` (full name), token-saving limits, and help tools
+
+### MCP Tools
+
+#### 🔍 Discovery & Help Tools (AI Start Here!)
+- `get_help(topic)`: **📖 Required reading!** Get usage guide and examples
+- `search_symbols(query, market)`: 🔍 Search by company name (e.g., "Apple", "Tesla")
+- `get_symbol_info(symbol)`: Get detailed symbol information
+- `ai_get_reference()`: AI quick reference guide
+
+#### Screening Tools
+- `screen_market`: Execute custom market screening queries
+- `get_top_gainers`: Find top gaining assets (includes full company names)
+- `get_top_losers`: Find top losing assets (includes full company names)
+- `get_most_active`: Most traded by volume
+- `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
+
+#### AI-Friendly Reference Tools
+- `search_available_fields`: Search for fields/columns by name or description
+- `get_field_info`: Get display name and type for a specific field
+- `get_code_example`: Get Python code examples for screener types
+- `list_fields_for_market`: List available fields with pagination
+- `get_common_fields_summary`: Get commonly used fields by category
+- `get_screener_preset`: Retrieve predefined screener presets
+- `get_market_metainfo`: Field definitions and allowed values per market
+
+### 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
+- `docs://params`: Screener params format and schema
+- `docs://screeners`: Predefined screener presets overview
+- `docs://fields`: Field display names (paginated)
+- `docs://markets`: Markets metadata
+- `docs://ai-reference`: AI quick reference guide
+- `docs://code-examples`: Python code examples for screeners
+
+## Installation
+
+### Using uvx (Recommended - No Install)
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+### Using uv
+```bash
+uv add tradingview-mcp
+```
+
+### Using pip
+```bash
+pip install tradingview-mcp
+```
+
+### From Source
+```bash
+git clone https://github.com/k73a/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
+
+#### Using uvx (Recommended)
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "uvx",
+      "args": ["tradingview-mcp"]
+    }
+  }
+}
+```
+
+#### Using installed package
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "tradingview-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### For AI Agents: Getting Started
+
+1. **First, call `ai_get_reference()`** to understand available markets, columns, and filters
+2. Use `search_available_fields("your query")` to find specific columns
+3. Use `get_code_example("Stocks (legacy)")` to see query patterns
+4. Build queries using `screen_market()` or `advanced_query()`
+
+### 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
+
+### Setup Development Environment
+```bash
+git clone https://github.com/k73a/tradingview-mcp.git
+cd tradingview-mcp
+uv sync --all-extras
+```
+
+### Running Tests
+```bash
+uv run pytest tests/ -v
+```
+
+### Code Formatting
+```bash
+uv run ruff format .
+uv run ruff check . --fix
+```
+
+### Type Checking
+```bash
+uv run pyright
+```
+
+### Debug Mode
+
+Enable structured debug responses from tools by setting:
+
+```bash
+export TRADINGVIEW_MCP_DEBUG=1
+```
+
+### Docs Data Path (Optional)
+
+If you want the full TradingView Screener docs datasets (e.g., large metainfo files),
+point the loader to your docs data directory:
+
+```bash
+export TRADINGVIEW_SCREENER_DOCS_DATA=/path/to/TradingView-Screener-docs/data
+```
+
+## Publishing & Releases
+
+This project uses GitHub Actions for automated publishing to PyPI:
+
+### Automatic Updates
+- **Weekly auto-update**: Every Monday, the workflow checks for dependency updates, runs tests, and publishes a new version if there are changes
+- **Manual trigger**: You can manually trigger updates from the GitHub Actions tab
+
+### Manual Release
+To create a manual release:
+
+1. Update version in `pyproject.toml`
+2. Commit and create a tag:
+   ```bash
+   git commit -am "Bump version to x.y.z"
+   git tag vx.y.z
+   git push origin main --tags
+   ```
+3. GitHub Actions will automatically build and publish to PyPI
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed release instructions.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

{tradingview_mcp-1.0.0 → tradingview_mcp-1.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "tradingview-mcp"
-version = "1.0.0"
+version = "1.0"
 description = "A comprehensive MCP server for TradingView market screening with integrated screener functionality"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
 authors = [{ name = "TradingView MCP Team" }]
-keywords = ["mcp", "tradingview", "screener", "crypto", "stocks", "trading", "technical-analysis"]
+keywords = ["mcp", "tradingview", "screener", "crypto", "stocks", "trading", "technical-analysis", "model-context-protocol"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -17,6 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
 dependencies = [
@@ -26,10 +27,18 @@ dependencies = [
     "httpx>=0.24.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/k73a/tradingview-mcp"
+Documentation = "https://github.com/k73a/tradingview-mcp#readme"
+Repository = "https://github.com/k73a/tradingview-mcp"
+Issues = "https://github.com/k73a/tradingview-mcp/issues"
+Changelog = "https://github.com/k73a/tradingview-mcp/blob/main/CHANGELOG.md"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
     "ruff>=0.1.0",
     "pyright>=1.1.0",
 ]
@@ -44,8 +53,15 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/tradingview_mcp"]
 
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
 [tool.hatch.build.targets.sdist]
-include = ["src/tradingview_mcp/**"]
+include = [
+    "src/tradingview_mcp/**/*.py",
+    "src/tradingview_mcp/**/*.json",
+    "src/tradingview_mcp/data/**",
+]
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]