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.
