-Sponsor-orange?style=for-the-badge&logo=github-sponsors){kind=icon}
-Sponsor-blueviolet?style=for-the-badge&logo=github-sponsors){kind=icon}
-Sponsor-gold?style=for-the-badge&logo=github-sponsors){kind=icon}
---
## 🎥 Framework Demo
https://github-production-user-asset-6210df.s3.amazonaws.com/67838093/478689497-4a605d98-43e8-49a6-8d3a-559315f6c01d.mp4
---
## 🆕 What's New
**Stability & Strategy Expansion (May 2026)**
- **Async hot-path tools** — 7 high-traffic tools (`yahoo_price`, `stock_extended_hours`, `top_gainers`, `volume_breakout_scanner`, `multi_timeframe_analysis`, `financial_news`, `combined_analysis`) converted to `async def`. FastMCP runs sync tools serialized on the event loop — async unlocks real intra-server parallelism so concurrent tool calls actually overlap. `combined_analysis` additionally fans its 3 sub-calls out via `asyncio.gather` for ~3× wall-clock improvement on the power tool. `yahoo_price` / `stock_extended_hours` use `httpx.AsyncClient` for true non-blocking I/O; sync-library tools (`tradingview_ta`, `tradingview-screener`, `feedparser`) are off-loaded via `asyncio.to_thread`. *(PR — open)*
- **9 backtest strategies** (up from 6) — added `rsi_pullback`, `keltner_breakout`, and `triple_ema`, covering trend-pullback, ATR-normalized breakout, and SMA200-filtered EMA cross edges. `compare_strategies` now ranks the full 9.
- **Resilience layer** — automatic retry + 60-second TTL cache on the TradingView screener provider, eliminating transient `"Expecting value"` errors on `combined_analysis` and `multi_timeframe_analysis`. *(PR [#32](https://github.com/atilaahmettaner/tradingview-mcp/pull/32) — merged)*
- **Financial news service rebuild** — replaces deprecated Reuters RSS endpoints with Yahoo Finance, MarketWatch, and CNBC. Fixes the long-standing `count: 0` bug on `financial_news`. *(PR [#33](https://github.com/atilaahmettaner/tradingview-mcp/pull/33) — merged)*
- **TA throttle** — caps concurrent `tradingview_ta` calls (default 4) + min 0.8s spacing between starts. Prevents parallel bursts of `combined_analysis` / `multi_timeframe_analysis` from hitting TradingView's empty-body rate-limit cliff. Tunable via env vars. *(PR [#34](https://github.com/atilaahmettaner/tradingview-mcp/pull/34) — merged)*
- **Walk-forward backtesting** (`walk_forward_backtest_strategy`) — train/test split with overfitting verdict (ROBUST / MODERATE / WEAK / OVERFITTED).
- **Hourly (1h) timeframe** support across `backtest_strategy`, `compare_strategies`, and `walk_forward_backtest_strategy`.
- **Full trade log + equity curve** outputs (`include_trade_log=True`, `include_equity_curve=True`).
---
## 🏗️ Architecture
---
## ✨ Why tradingview-mcp?
| Feature | `tradingview-mcp` | Traditional Setups | Bloomberg Terminal |
|---------|-------------------|--------------------|--------------------|
| **Setup Time** | 5 minutes | Hours (Docker, Conda...) | Weeks (Contracts) |
| **Cost** | Free & Open Source | Variable | $30k+/year |
| **Backtesting** | ✅ 9 strategies + Walk-forward + Sharpe | ❌ Manual scripting | ✅ Proprietary |
| **Live Sentiment** | ✅ Reddit + RSS news | ❌ Separate setup | ✅ Terminal |
| **Market Data** | ✅ Live / Real-Time | Historical / Delayed | Live |
| **API Keys** | **None required** | Multiple (OpenAI, etc.) | N/A |
---
## 🚀 Quick Start (5 Minutes)
**Two ways to run it — the same 37 tools either way:**
| | 🧑💻 Self-host (this repo) | ☁️ Hosted — [pro.cryptosieve.com](https://pro.cryptosieve.com) |
|---|---|---|
| **Price** | Free forever (MIT) | $9/mo Pro · $29/mo Pro+ · 3-day trial |
| **Time to first call** | ~5 minutes (Python + `uv`) | ~60 seconds (paste one URL) |
| **Updates & ops** | You run and update it | Managed — always on the latest |
| **Runs on** | Your machine or VPS | Hosted, streamed from the edge |
| **Limits** | Your hardware | 2,500/mo · 60/min (Pro) → 10,000/mo · 150/min (Pro+) |
| **Best for** | Tinkerers, forkers, full control | Folks who'd rather skip the ops |
> ☁️ **Zero setup:** paste one connector URL into Claude.ai, ChatGPT, Copilot, or Cursor → **[start a 3-day free trial](https://pro.cryptosieve.com)**. Everything below is for self-hosting.
### Install via pip
```bash
pip install tradingview-mcp-server
```
### Optional: news & sentiment (free Marketaux key)
`financial_news` and `market_sentiment` (plus the news/sentiment parts of
`combined_analysis`) are powered by [Marketaux](https://www.marketaux.com/) —
licensed market news with per-entity sentiment. Grab a **free API key**
(100 requests/day; the server caches for 4h and shares one fetch between news
and sentiment, so the free tier goes a long way) and set:
```bash
export MARKETAUX_API_TOKEN=your_token_here # optional
```
Without a token those two tools return a friendly "not configured" note — all
other tools work normally.
### Claude Desktop Config (`claude_desktop_config.json`)
> **Note:** On macOS, GUI apps like Claude Desktop may not have `~/.local/bin` in their PATH. Use the full path to `uvx` to avoid "command not found" errors.
```json
{
"mcpServers": {
"tradingview": {
"command": "/Users/YOUR_USERNAME/.local/bin/uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
On Linux, replace `/Users/YOUR_USERNAME` with `/home/YOUR_USERNAME`. On Windows, use `%USERPROFILE%\.local\bin\uvx.exe`.
### Codex Plugin Config
This repository also includes mcp-only Codex plugin metadata:
- `.codex-plugin/plugin.json`
- `.codex-mcp.json`
The plugin uses the same PyPI package entrypoint:
```json
{
"mcpServers": {
"tradingview": {
"command": "uvx",
"args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
After installing or enabling the Codex plugin, restart Codex so the MCP server is loaded in the next session. Depending on your Codex version, `codex mcp list` may show registered MCP servers, but tool availability should be verified in a fresh Codex session.
### Or run from source
```bash
git clone https://github.com/atilaahmettaner/tradingview-mcp
cd tradingview-mcp
uv run tradingview-mcp
```
---
## 🛠️ Troubleshooting
### 🪟 Windows: `MCP error -32001: Request timed out` on first launch
Symptom — you see this in the Claude Desktop logs shortly after adding the config:
```
[tradingview] Server started and connected successfully
[tradingview] Message from client: initialize ...
[60 seconds later]
[tradingview] notifications/cancelled — reason: "MCP error -32001: Request timed out"
```
**Why it happens:** Python 3.14 is not supported yet. `uvx` downloads `tradingview-mcp-server`, creates a fresh virtualenv, and installs dependencies the first time it runs. Some native dependencies in the MCP stack do not currently publish compatible Python 3.14 wheels, so installation can fall back to source builds or fail before Claude Desktop finishes initializing the server.
**Fix — pin to Python 3.13 (has prebuilt pandas wheels):**
```json
{
"mcpServers": {
"tradingview": {
"command": "uvx",
"args": ["--python", "3.13", "--from", "tradingview-mcp-server", "tradingview-mcp"]
}
}
}
```
On macOS use the full path to `uvx` (see the note in Quick Start). On Windows `uvx` is typically `%USERPROFILE%\.local\bin\uvx.exe`.
**Alternative — pre-install once, then let Claude Desktop reuse the cache:**
```bash
# Run in a terminal before launching Claude Desktop
uv tool install --python 3.13 tradingview-mcp-server
```
After the install finishes, start Claude Desktop with the normal config and the server will come up instantly (cache is already warm).
> _Credit: [@wyh4444](https://github.com/wyh4444) for the original report in [#24](https://github.com/atilaahmettaner/tradingview-mcp/issues/24)._
---
## ⚠️ Error Envelope Format
Tools that have adopted the structured error format return either their normal payload **or** an error envelope:
```json
{"error": {"code": "ALL_BATCHES_FAILED", "message": "All 5 batches failed; first error: JSONDecodeError(...)", "batches_attempted": 5, "batches_failed": 5, "first_error": "..."}}
```
**Why:** the previous `[]` / `{"error": "Analysis failed: ..."}` strings made it impossible to distinguish "no matches today" from "upstream rate-limit cliff." The new envelope is programmatically branchable by `code`.
**Currently adopted by:** `top_gainers`, `top_losers`, `rating_filter`, `volume_breakout_scanner`, `smart_volume_scanner`. More tools will follow in subsequent PRs.
**Detecting an error:**
```python
result = volume_breakout_scanner(exchange="KUCOIN")
if isinstance(result, dict) and "error" in result:
code = result["error"]["code"]
if code == "ALL_BATCHES_FAILED":
# Wait + retry, raise alert, fall back to single-batch call, etc.
...
else:
for row in result:
...
```
Stable codes are defined in [`core/errors.py`](https://github.com/atilaahmettaner/tradingview-mcp/blob/HEAD/src/tradingview_mcp/core/errors.py).
---
## 📱 Use via Telegram, WhatsApp & More (OpenClaw)
Connect this server to **Telegram, WhatsApp, Discord** and 20+ messaging platforms using [OpenClaw](https://openclaw.ai) — a self-hosted AI gateway. **Tested & verified on Hetzner VPS (Ubuntu 24.04).**
### How It Works
> OpenClaw routes Telegram messages to an AI agent. The agent uses `trading.py` — a thin Python wrapper — to call `tradingview-mcp` functions and return formatted results. **No MCP protocol needed between OpenClaw and the server; it's a direct Python import.**
```
Telegram → OpenClaw agent (AI model) → trading.py (bash) → tradingview-mcp → Yahoo Finance
```
### Quick Setup
```bash
# 1. Install UV and tradingview-mcp
curl -LsSf https://astral.sh/uv/install.sh | sh && source ~/.bashrc
uv tool install tradingview-mcp-server
# 2. Configure OpenClaw channels
cat > ~/.openclaw/openclaw.json << 'EOF'
{
channels: {
telegram: {
botToken: "YOUR_BOT_TOKEN_HERE",
},
},
}
EOF
# 3. Configure gateway + agent
openclaw config set gateway.mode local
openclaw config set acp.defaultAgent main
# 4. Set your AI model (choose ONE option below)
openclaw configure --section model
# 5. Install the skill + tool wrapper
mkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools
curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/SKILL.md \
-o ~/.agents/skills/tradingview-mcp/SKILL.md
curl -fsSL https://raw.githubusercontent.com/atilaahmettaner/tradingview-mcp/main/openclaw/trading.py \
-o ~/.openclaw/tools/trading.py && chmod +x ~/.openclaw/tools/trading.py
# 6. Start the gateway
openclaw gateway install
systemctl --user start openclaw-gateway.service
```
### Choose Your AI Model
OpenRouter is **not required** — use whichever provider you have a key for:
| Provider | Model ID for OpenClaw | Get Key |
|----------|----------------------|---------|
| **OpenRouter** (aggregator — access to all models) | `openrouter/google/gemini-3-flash-preview` | [openrouter.ai/keys](https://openrouter.ai/keys) |
| **Anthropic** (Claude direct) | `anthropic/claude-sonnet-4-5` | [console.anthropic.com](https://console.anthropic.com) |
| **Google** (Gemini direct) | `google/gemini-2.5-flash` | [aistudio.google.com](https://aistudio.google.com) |
| **OpenAI** (GPT direct) | `openai/gpt-4o-mini` | [platform.openai.com](https://platform.openai.com) |
```bash
# Examples — set your chosen model:
openclaw config set agents.defaults.model "openrouter/google/gemini-3-flash-preview" # via OpenRouter
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-5" # Anthropic direct
openclaw config set agents.defaults.model "google/gemini-2.5-flash" # Google direct
```
> ⚠️ **Important:** Prefix must match your provider. `google/...` needs a Google API key. `openrouter/...` needs an OpenRouter key.
### ⚠️ Common Mistakes
| Symptom | Cause | Fix |
|---------|-------|-----|
| `Unrecognized keys: mcpServers` | `mcpServers` not supported in this version | Remove from config, use bash wrapper |
| `No API key for provider "google"` | Used `google/model` but only have OpenRouter key | Use `openrouter/google/model` instead |
| `which agent?` loop | `acp.defaultAgent` not set | `openclaw config set acp.defaultAgent main` |
| Gateway won't start | `gateway.mode` missing | `openclaw config set gateway.mode local` |
### Test Your Bot
Once running, send your Telegram bot:
```
market snapshot
backtest RSI strategy for AAPL, 1 year
compare all strategies for BTC-USD
```
👉 **[Full OpenClaw Setup Guide →](https://github.com/atilaahmettaner/tradingview-mcp/blob/HEAD/OPENCLAW.md)**
---
Unlike basic screeners, this framework deploys **specialized AI agents** that debate findings in real-time:
1. **🛠️ Technical Analyst** — Bollinger Bands (±3 proprietary rating), RSI, MACD
2. **🌊 Sentiment & Momentum Analyst** — Reddit community sentiment + price momentum
3. **🛡️ Risk Manager** — Volatility, drawdown risk, mean-reversion signals
*Output: `STRONG BUY` / `BUY` / `HOLD` / `SELL` / `STRONG SELL` with confidence score*
---
## 🔧 All 37 MCP Tools
### 📊 Backtesting Engine
| Tool | Description |
|------|-------------|
| `backtest_strategy` | Backtest 1 of 9 strategies with institutional metrics (Sharpe, Calmar, Expectancy). Supports `1d` and `1h` timeframes; optional full trade log + equity curve. |
| `compare_strategies` | Run all 9 strategies on the same symbol and rank by performance. |
| `walk_forward_backtest_strategy` | Train/test split walk-forward validation with overfitting verdict (ROBUST / MODERATE / WEAK / OVERFITTED). |
**9 Strategies to Test:**
- `rsi` — RSI oversold/overbought mean reversion
- `bollinger` — Bollinger Band mean reversion
- `macd` — MACD golden/death cross
- `ema_cross` — EMA 20/50 Golden/Death Cross
- `supertrend` — ATR-based Supertrend trend following 🔥
- `donchian` — Donchian Channel breakout (Turtle Trader style)
- `rsi_pullback` — Dip-buy in confirmed uptrend (SMA50>SMA200 + RSI<40 entry) 🆕
- `keltner_breakout` — ATR-normalized breakout (EMA20 + 2·ATR upper band) 🆕
- `triple_ema` — EMA 20/50 cross gated by SMA200 trend filter 🆕
> 🆕 strategies require `period='1y'` or `'2y'` so the SMA200 trend filter can complete its warmup.
**Metrics you get:** Win Rate, Total Return, Sharpe Ratio, Calmar Ratio, Max Drawdown, Profit Factor, Expectancy, Best/Worst Trade, vs Buy-and-Hold, with **realistic commission + slippage simulation**.
```
Example prompt: "Compare all 9 strategies on MSFT for 2 years"
→ #1 triple_ema: +15.1% | Sharpe: 0.0 | WR: 100%
→ #2 keltner_breakout: +14.3% | Sharpe: 4.7 | WR: 40%
→ #3 bollinger: +12.2% | Sharpe: 4.1 | WR: 64%
→ Buy & Hold: -2.1%
```
---
### 💰 Yahoo Finance — Real-Time Prices *(New in v0.6.0)*
| Tool | Description |
|------|-------------|
| `yahoo_price` | Real-time quote: price, change %, 52w high/low, market state |
| `market_snapshot` | Global overview: S&P500, NASDAQ, VIX, BTC, ETH, EUR/USD, SPY, GLD |
**Supports:** Stocks (AAPL, TSLA, NVDA), Crypto (BTC-USD, ETH-USD, SOL-USD), ETFs (SPY, QQQ, GLD), Indices (^GSPC, ^DJI, ^IXIC, ^VIX), FX (EURUSD=X), Turkish (THYAO.IS, SASA.IS)
---
### 🌍 Global Stock Screener — Common & Preferred Shares
| Tool | Description |
|------|-------------|
| `stock_screener` | List common or preferred stocks for any TradingView country market (america, korea, germany, brazil, …) with price, currency, % change, dividend yield — ranked by market cap. The API twin of TradingView's "Common stock" / "Preferred stock" symbol-search filter. |
| `stock_prices` | Direct price lookup for specific symbols (comma-separated `EXCHANGE:SYMBOL`, e.g. `NASDAQ:NVDA, KRX:005930`) — price, currency, daily % change, with unrecognized tickers named in `not_found`. |
---
### 🧠 AI Sentiment & Intelligence
| Tool | Description |
|------|-------------|
| `market_sentiment` | Reddit sentiment across finance communities (bullish/bearish score, top posts) |
| `financial_news` | Live RSS headlines from Yahoo Finance, MarketWatch, CNBC, CoinDesk, CoinTelegraph |
| `combined_analysis` | **Power Tool**: TradingView technicals + Reddit sentiment + live news → confluence decision. Now backed by retry + 60s cache for resilience against transient screener errors. |
---
### 📈 Technical Analysis Core
| Tool | Description |
|------|-------------|
| `get_technical_analysis` | Full TA: RSI, MACD, Bollinger, 23 indicators with BUY/SELL/HOLD |
| `get_multiple_analysis` | Bulk TA for multiple symbols at once |
| `get_bollinger_band_analysis` | Proprietary ±3 BB rating system |
| `get_stock_decision` | 3-layer decision engine (ranking + trade setup + quality score) |
| `screen_stocks` | Multi-exchange screener with 20+ filter criteria |
| `scan_by_signal` | Scan by signal type (oversold, trending, breakout...) |
| `get_candlestick_patterns` | 15 candlestick pattern detector |
| `get_multi_timeframe_analysis` | Weekly→Daily→4H→1H→15m alignment analysis |
---
### 🌍 Multi-Exchange Support
| Exchange | Tools |
|----------|-------|
| **Binance** | Crypto screener, all pairs |
| **KuCoin / Bybit+** | Crypto screener |
| **NASDAQ / NYSE** | US stocks (AAPL, TSLA, NVDA...) |
| **EGX (Egypt)** | `egx_market_overview`, `egx_stock_screener`, `egx_trade_plan`, `egx_fibonacci_retracement` |
| **Turkish (BIST)** | Via TradingView screener |
---
## 💬 Example AI Conversations
```
You: "Give me a full market snapshot right now"
AI: [market_snapshot] → S&P500 -3.4%, BTC +0.1%, VIX 31 (+13%), EUR/USD 1.15
You: "What is Reddit saying about NVDA?"
AI: [market_sentiment] → Strongly Bullish (0.41) | 23 posts | 18 bullish
You: "Backtest RSI strategy on BTC-USD for 2 years"
AI: [backtest_strategy] → +31.5% return | 100% win rate | 2 trades | B&H: -5%
You: "Which of the 9 strategies worked best on MSFT in the last 2 years?"
AI: [compare_strategies] → triple_ema #1 (+15.1%, WR 100%), keltner_breakout #2 (+14.3%), macd last (-23.4%)
You: "Run walk-forward backtest on supertrend for SPY"
AI: [walk_forward_backtest_strategy] → Verdict: ROBUST (avg robustness 0.92) | OOS return +8.5%
You: "Analyze TSLA with all signals: technical + sentiment + news"
AI: [combined_analysis] → BUY (Technical STRONG BUY + Bullish Reddit + Positive news)
```
---
## 💖 Support the Project
This framework is **free and open source**, built in spare time. If it saves you hours of research or helps you make better decisions, please consider sponsoring:
| Tier | Monthly | What You Get |
|------|---------|--------------|
| ☕ Coffee | $5 | Heartfelt gratitude + name in README |
| 🚀 Supporter | $15 | Above + priority bug fixes |
| 💎 Pro | $30 | Above + priority feature requests |
Every sponsor directly funds new features like Walk-Forward Backtesting, Twitter/X sentiment, and managed cloud hosting.
---
## 📋 Roadmap
- [x] TradingView technical analysis (30+ indicators)
- [x] Multi-exchange screener (Binance, KuCoin, MEXC, EGX, US stocks)
- [x] Reddit sentiment analysis
- [x] Live financial news (Yahoo / MarketWatch / CNBC / CoinDesk / CoinTelegraph)
- [x] Yahoo Finance real-time prices
- [x] Backtesting engine (9 strategies + Sharpe / Calmar / Expectancy)
- [x] Walk-forward backtesting (overfitting detection)
- [x] Resilience layer (retry + TTL cache) on screener provider
- [x] Hourly (1h) backtesting timeframe
- [ ] Twitter/X market sentiment
- [ ] Paper trading simulation
- [ ] Managed cloud hosting (no local setup)
---
## 📄 License
MIT License — see [LICENSE](https://github.com/atilaahmettaner/tradingview-mcp/tree/HEAD/LICENSE) for details.
---
*Disclaimer: This tool is for educational and research purposes only. It does not constitute financial advice. Always do your own research before making investment decisions.*