tradingview-assistant 0.8.1

Advanced AI Trading Intelligence Framework — MCP server with walk-forward backtesting, trade logs, equity curves, 1h timeframe, sentiment, Yahoo Finance, and 30+ technical analysis tools

tradingview-assistant — AI Trading Intelligence MCP Server

Author: DEBARPAN BOSE CHOWDHURY
Repository: https://github.com/DEBARPAN2000/tradingview-mcp
PyPI: tradingview-assistant

The most complete open-source AI trading toolkit for Claude and MCP-compatible clients.
40+ tools · Backtesting · Walk-Forward Validation · Live Sentiment · Yahoo Finance · Paper Trading — no API keys required.

---

Table of Contents

• Why tradingview-assistant?
• Architecture
• Quick Start
• MCP Setup
• All Tools
• Example Prompts
• Docker
• OpenClaw (Telegram / WhatsApp)
• Troubleshooting
• Project Structure
• Contributing
• License

---

Why tradingview-assistant?

Feature	This Server	Typical DIY Setup	Bloomberg Terminal
Setup Time	2 minutes	Hours	Weeks
Cost	Free & Open Source	Variable	~$30k/year
API Keys Required	None	Multiple	N/A
Backtesting	6 strategies + walk-forward	Manual scripting	Proprietary
Live Sentiment	Reddit + RSS news	Separate service	Terminal only
Market Coverage	Crypto + 12 stock markets	Limited	Broad
Multi-Agent Analysis	3-agent AI debate	Not available	Not available
Paper Trading	Built-in SQLite persistence	Not available	Not available

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│               Claude Desktop / MCP-Compatible Client            │
└──────────────────────────┬──────────────────────────────────────┘
                           │  MCP Protocol (stdio or HTTP)
┌──────────────────────────▼──────────────────────────────────────┐
│               tradingview-assistant MCP Server                  │
│                       (server.py)                               │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   Screener   │  │   Backtest   │  │  Sentiment & News    │  │
│  │   Service    │  │   Service    │  │      Service         │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
│         │                 │                      │              │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────────▼───────────┐  │
│  │  TradingView │  │ Yahoo Finance│  │  Reddit API + RSS    │  │
│  │  Screener    │  │     API      │  │       Feeds          │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  Portfolio   │  │  Risk &      │  │   Market Adapters    │  │
│  │  Service     │  │  Correlation │  │  (EGX, NSE, BIST…)  │  │
│  │  (SQLite)    │  │  Tools       │  │                      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Layer overview

Layer	Location	Responsibility
Transport	server.py	MCP tool registry, input validation, response shaping
Services	core/services/*.py	Business logic — screener, backtest, sentiment, EGX, NSE, risk
Adapters	core/services/market_adapters/	Market-specific logic (EGX, NSE)
Static Data	core/data/	EGX and NSE sector / index datasets
Utils	core/utils/	Input validators, error contracts
Portfolio	core/portfolio.py	SQLite-backed paper trading persistence

---

Quick Start

Option 1 — PyPI install (recommended)

pip install tradingview-assistant

Option 2 — uvx (zero-install, always latest)

uvx --from tradingview-assistant tradingview-mcp

Option 3 — Source

git clone https://github.com/DEBARPAN2000/tradingview-mcp.git
cd tradingview-mcp
uv sync
uv run tradingview-mcp

For detailed instructions (Docker, virtual envs, Claude Desktop, troubleshooting) see INSTALLATION.md.

---

MCP Setup

Claude Desktop (claude_desktop_config.json)

macOS / Linux:

{
  "mcpServers": {
    "tradingview": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["--from", "tradingview-assistant", "tradingview-mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "tradingview": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "tradingview-assistant", "tradingview-mcp"]
    }
  }
}

macOS note: GUI apps may not have ~/.local/bin in PATH. Use the full absolute path to uvx.
Windows note: Pin --python 3.13 to use prebuilt wheels and avoid the 60-second initialization timeout.

HTTP / Streamable-HTTP transport

tradingview-mcp streamable-http --host 0.0.0.0 --port 8000

Metrics endpoints:

Endpoint	Format	Description
GET /metrics/rate_limit	JSON	Rate limiting stats
GET /metrics/observability	JSON	Tool usage and latency
GET /metrics/prometheus	Text	Prometheus scrape target

---

All Tools

For the complete parameter reference — types, defaults, valid values, and example prompts for every tool — see TOOLS.md.

Screener Tools

Tool	Description
top_gainers	Top gaining assets by % change
top_losers	Top losing assets by % change
bollinger_scan	Bollinger Band Width squeeze detection
rating_filter	Filter by BB rating -3 (Strong Sell) to +3 (Strong Buy)

Asset Analysis

Tool	Description
coin_analysis	Full TradingView indicator stack for any asset
multi_timeframe_analysis	Weekly → Daily → 4H → 1H → 15m trend alignment
multi_agent_analysis	3-agent debate: Technical + Sentiment + Risk
combined_analysis	Power tool: TA + Reddit + News confluence score

Candle Pattern Tools

Tool	Description
consecutive_candles_scan	N consecutive bullish or bearish candles across exchange
advanced_candle_pattern	Multi-timeframe accelerating candle size detection

Volume Scanner Tools

Tool	Description
volume_breakout_scanner	Volume spike combined with price breakout
volume_confirmation_analysis	Single-asset volume vs. price confirmation
smart_volume_scanner	Volume ratio + RSI condition filter

EGX — Egyptian Exchange (7 tools)

Tool	Description
egx_market_overview	Full EGX market snapshot
egx_sector_scan	Scan by sector or list all sectors
egx_sector_scanner	Sector rotation hot/cold with top stock picks
egx_index_analysis	EGX30 / EGX70 / EGX100 / SHARIAH33 constituent analysis
egx_stock_screener	Composite scoring engine for EGX stocks
egx_trade_plan	Entry, stop-loss, target, R:R for any EGX stock
egx_fibonacci_retracement	Fibonacci levels from swing high/low

Sentiment & News

Tool	Description
market_sentiment	Real-time Reddit community sentiment
financial_news	RSS financial news from Reuters, CoinDesk, etc.

Backtesting (3 tools)

Tool	Description
backtest_strategy	Single strategy with Sharpe, Calmar, Max Drawdown
compare_strategies	All 6 strategies ranked by total return
walk_forward_backtest_strategy	Walk-forward folds to detect overfitting

6 strategies: rsi · bollinger · macd · ema_cross · supertrend · donchian

Yahoo Finance

Tool	Description
yahoo_price	Real-time price for stocks, crypto, ETF, FX, indices
market_snapshot	Global macro overview in one response

Portfolio & Paper Trading

Tool	Description
execute_order	Submit a paper BUY/SELL order
execute_portfolio_trade	Direct portfolio trade with 30% position-size guard
get_user_portfolio	Holdings, P&L, cash balance
get_portfolio_trade_history	Full audit log of paper trades

Signals & Alerts

Tool	Description
save_trade_signal	Persist a signal for replay/audit
list_trade_signals	List stored signals
set_user_alert_preferences	Configure alert delivery channel
dispatch_trade_alert	Fire alert using stored preferences

NSE — India

Tool	Description
nse_sector_list	All NSE sectors
nse_market_overview	Overview with Nifty 50, Nifty Bank, Nifty IT

Risk & Correlation

Tool	Description
get_kelly_position_size	Kelly Criterion optimal position fraction
get_trade_levels	Stop-loss and take-profit price levels
assess_portfolio_trade_risk	Full pre-trade risk assessment
compute_portfolio_correlation	Pairwise Pearson correlation matrix

---

Example Prompts

# Screening
"Show top gainers on KuCoin 15m"
"Run a Bollinger squeeze scan on Binance 4h"
"Find NASDAQ strong buy signals"

# Analysis
"Full technical analysis of BTCUSDT on Binance 4h"
"Multi-timeframe analysis of ETHUSDT on KuCoin"
"Run a 3-agent debate on AAPL NASDAQ daily"
"Combined technical + sentiment + news for TSLA"

# EGX
"EGX market overview today"
"Scan EGX banks sector"
"Generate a trade plan for COMI"
"EGX30 index analysis"

# Backtesting
"Backtest RSI strategy on AAPL for 1 year"
"Compare all 6 strategies on BTC-USD 2 years"
"Walk-forward validate MACD on SPY — is it overfitted?"

# Real-time data
"What is Apple's current price?"
"Global market snapshot"
"Latest crypto news"

# Portfolio
"Paper buy 0.1 BTC at 45000 for user alice"
"Show my portfolio for user alice"

# Risk
"Kelly position size: 55% win rate, 2:1 reward/risk"
"Trade levels for long at 45000, 3% stop, 9% target"

---

Docker

# Pull and run
docker pull debarpan2000/tradingview-mcp:latest
docker run -p 8000:8000 debarpan2000/tradingview-mcp:latest

# Or with docker compose
docker compose up -d

Claude Desktop config for Docker:

{
  "mcpServers": {
    "tradingview": {
      "command": "curl",
      "args": ["-s", "http://localhost:8000/mcp"]
    }
  }
}

---

OpenClaw (Telegram / WhatsApp)

Route Claude through Telegram, WhatsApp, Discord, and 20+ messaging platforms with OpenClaw:

Telegram message -> OpenClaw agent -> trading.py -> tradingview-assistant -> result

# Install the tool
uv tool install tradingview-assistant

# Install the skill and wrapper
mkdir -p ~/.agents/skills/tradingview-mcp ~/.openclaw/tools
curl -fsSL https://raw.githubusercontent.com/DEBARPAN2000/tradingview-mcp/main/openclaw/SKILL.md \
  -o ~/.agents/skills/tradingview-mcp/SKILL.md
curl -fsSL https://raw.githubusercontent.com/DEBARPAN2000/tradingview-mcp/main/openclaw/trading.py \
  -o ~/.openclaw/tools/trading.py && chmod +x ~/.openclaw/tools/trading.py

openclaw gateway install && systemctl --user start openclaw-gateway.service

See OPENCLAW.md for the full setup guide, multi-provider AI model options, and common mistakes.

---

Troubleshooting

Windows: MCP timeout on first launch

Symptom: MCP error -32001: Request timed out in Claude Desktop logs.

Cause: uvx compiles pandas from source on Python 3.14 (no prebuilt wheel), exceeding the 60-second timeout.

Fix — pin to Python 3.13:

{
  "mcpServers": {
    "tradingview": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "tradingview-assistant", "tradingview-mcp"]
    }
  }
}

Or pre-warm the cache once:

uv tool install --python 3.13 tradingview-assistant

macOS: uvx: command not found

Use the absolute path in your config: /Users/YOUR_USERNAME/.local/bin/uvx

No symbols returned for an exchange

Check the exchange code is uppercase and supported: KUCOIN, BINANCE, BYBIT, MEXC, OKX, EGX, NASDAQ, NYSE, BIST, etc.

TradingView rate limiting

Space out scans by a few seconds. The server has a built-in request guard with configurable rate limits.

---

Project Structure

tradingview-mcp/
├── src/tradingview_mcp/
│   ├── server.py                        # MCP tool registry (40+ tools)
│   ├── coinlist/                        # Per-exchange symbol lists
│   └── core/
│       ├── services/
│       │   ├── backtest_service.py      # 6-strategy backtesting engine
│       │   ├── egx_service.py           # Egyptian Exchange tools
│       │   ├── correlation_service.py   # Portfolio correlation
│       │   ├── risk_service.py          # Kelly, trade levels, risk checks
│       │   ├── portfolio_service.py     # Paper trading execution
│       │   ├── alert_service.py         # Alert delivery
│       │   ├── data_source.py           # TradingView screener integration
│       │   ├── http_client.py           # Shared HTTP client
│       │   └── market_adapters/         # EGX and NSE adapters
│       ├── data/                        # Static datasets (sectors, indices)
│       ├── utils/                       # Validators and error contracts
│       └── portfolio.py                 # SQLite persistence layer
├── tests/
│   ├── unit/                            # Unit tests
│   └── integration/                     # Live integration tests
├── scripts/
│   └── repo_hygiene_check.py            # Security hygiene checker
├── openclaw/
│   ├── SKILL.md                         # OpenClaw skill definition
│   └── trading.py                       # OpenClaw tool wrapper
├── Dockerfile
├── docker-compose.yml
├── TOOLS.md                             # Complete tool reference
├── INSTALLATION.md                      # Detailed installation guide
├── OPENCLAW.md                          # OpenClaw integration guide
├── CONTRIBUTING.md                      # Contribution guide
└── SECURITY.md                          # Security policy

---

Contributing

See CONTRIBUTING.md for the full guide.

Quick steps:

1. Fork and clone the repo
2. uv sync to install all dependencies
3. uv run pytest tests/unit/ to verify your setup
4. Create a feature branch, make changes, run tests
5. Open a PR against main with a clear description

---

License

MIT © 2025 DEBARPAN BOSE CHOWDHURY — see LICENSE.