The Problem
Clients that need bulk market data (stocks, crypto, forex, bonds, futures, coins) must scrape TradingView’s web UI or write ad‑hoc HTTP calls. Those approaches are fragile, require manual parsing of HTML/JSON, and provide no typed, query‑builder interface, making integration into Python analytics pipelines error‑prone.
What This Does
tvscreener supplies a pure‑Python wrapper that talks to TradingView’s public screener endpoints and returns results as a pandas DataFrame. The library defines a separate screener class per market type (StockScreener, CryptoScreener, etc.) in tvscreener/core/. Each screener exposes a fluent, type‑safe API built on field enums (e.g., tvscreener/field/stock.py) and filter objects (tvscreener/filter.py).
The repository also ships a lightweight MCP (Model Context Protocol) server (tvscreener/mcp/server.py and tvscreener/mcp/main.py) that exposes the same query capabilities over HTTP, enabling AI assistants (Claude, etc.) to request market data without embedding the library.
Documentation lives under docs/ with markdown API reference, quick‑start notebooks, and a web‑based code generator (static assets in app/). The generator is built from pre‑computed field metadata in .dev/codegen/data/.
How To Use It
Setup
Install core library pip install tvscreener
Install with MCP server support (optional)
pip install "tvscreener[mcp]"
Both commands are derived from the pyproject.toml and requirements.txt which list pandas, requests, fastapi, and uvicorn.
Configuration
No API keys are required—the library scrapes publicly available endpoints. If the MCP server runs behind a reverse proxy, configure the host/port via environment variables HOST and PORT before launching (tvscreener/mcp/server.py reads them).
Running the Library
from tvscreener import StockScreener, StockField
ss = StockScreener() ss.select(StockField.NAME, StockField.PRICE, StockField.CHANGEPERCENT) ss.where(StockField.PRICE > 100) df = ss.get() # returns pandas DataFrame print(df.head())
The example mirrors the usage shown in docs/getting-started/quickstart.md.
Running the MCP Server
Entry point defined in tvscreener/mcp/main.py tvscreener-mcp # installs console script via the [mcp] extra
The server starts a FastAPI app on http://127.0.0.1:8000. Endpoints such as /discoverfields and /customquery are implemented in tvscreener/mcp/tools.py.
Real‑World Use
A quant team can embed the library in a nightly data‑ingestion pipeline:
from tvscreener import CryptoScreener, CryptoField import pandas as pd
cs = CryptoScreener() cs.select(CryptoField.SYMBOL, CryptoField.PRICE, CryptoField.VOLUME24H) cs.where(CryptoField.MARKETCAP > 1e9) cryptodf = cs.get() cryptodf.toparquet("s3://data/crypto/daily.parquet")
Alternatively, a Claude‑powered chatbot can call the MCP endpoint to answer user queries like “Show the top 10 gainers in the crypto screener”.
Code Health & Issues
Low – Missing lockfile – pyproject.toml defines dependencies but there is no poetry.lock or requirements.lock, making reproducible builds harder. Low – Limited error handling – Network calls in tvscreener/util.py raise raw requests exceptions; the library does not retry on transient failures. Medium – No explicit rate‑limit handling – TradingView may throttle; the client does not back‑off, risking HTTP 429 errors in production. Low – Tests exist but coverage is modest – 14 test files cover core functionality, and CI runs pytest via GitHub Actions (.github/workflows/codecov.yml). No integration tests for the MCP server. Low – Documentation is extensive – docs/ includes API reference, notebooks, and a code‑generator guide, matching the code base. Low – License present – LICENSE is included (MIT).
Overall the repo follows a clean package layout, uses type hints (tvscreener/py.typed), and ships a CI pipeline with code‑cov reporting.
The Bottom Line
tvscreener provides a well‑documented, type‑safe Python API for pulling TradingView screener data, plus an optional MCP server for AI‑driven access. The codebase is small, test‑covered, and easy to integrate, though production users should add retry/ratelimit logic and consider pinning dependencies via a lockfile. Ideal for data‑science teams needing programmatic market data without building their own scraper.