# TradingView MCP — AI Trading Copilot

Your personal AI trading assistant that sees your TradingView chart, understands your trading style, and coaches you through every decision.

**84 MCP tools | 30 skills | 32 slash commands | Telegram alerts | Dhan broker bridge | trader profile**

---

## One-Click Install

Paste this into **Claude Code** and it handles everything:

```
Install the TradingView MCP server from https://github.com/frozo-ai/frozo-tradingview-mcp.git — clone it, run npm install, add it to my .mcp.json, launch TradingView with debug port, and verify with tv_health_check. Then run /tv-profile-setup to set up my trader profile.
```

Or for **any AI assistant with MCP support** (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "tradingview": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "/path/to/frozo-tradingview-mcp"
    }
  }
}
```

---

## Demo — Real Live Data from TradingView

Every number below is pulled live from a running TradingView chart via CDP:

![Demo](demo/tradingview-mcp-demo.gif)

> **Run it yourself:** `bash demo/claude-demo.sh` (requires TradingView Desktop running)

---

## How It Works

```
Claude Code / Desktop / Cursor
       |
       | MCP protocol (stdio)
       v
  TradingView MCP Server (Node.js, 84 tools)
       |
       | Chrome DevTools Protocol (localhost:9222)
       v
  TradingView Desktop (Electron)
       |
  +----+----+----+
  |         |         |
Trader    Telegram   Dhan Broker
Profile   Bot API    (MCP bridge)
```

> [!WARNING]
> **Not affiliated with TradingView Inc. or Anthropic.** Interacts with your locally running TradingView Desktop via Chrome DevTools Protocol. Review the [Disclaimer](#disclaimer) before use.

> [!IMPORTANT]
> **Requires a valid TradingView subscription.** Does not bypass any access controls. All data stays on your machine.

---

## What Makes This Different

Most trading tools give you data. This one gives you a **trading coach** that:

- Knows YOUR trading rules and enforces them
- Validates every trade against YOUR checklist before you enter
- Watches for YOUR behavioral weaknesses (revenge trading, cutting winners)
- Sizes positions using YOUR risk parameters with F&O lot size awareness
- Runs YOUR pre-market routine automatically every morning
- Sends alerts to YOUR phone via Telegram
- Bridges directly to YOUR Dhan broker for execution
- Reviews YOUR journal and finds patterns YOU can't see

---

## Quick Start

### 1. Install

```bash
git clone https://github.com/frozo-ai/frozo-tradingview-mcp.git
cd frozo-tradingview-mcp
npm install
```

### 2. Launch TradingView with CDP

```bash
# Mac
./scripts/launch_tv_debug_mac.sh

# Windows
scripts\launch_tv_debug.bat

# Linux
./scripts/launch_tv_debug_linux.sh

# Or manually on any platform
/path/to/TradingView --remote-debugging-port=9222
```

### 3. Connect to Claude Code

Add to your project `.mcp.json`:
```json
{
  "mcpServers": {
    "tradingview": {
      "command": "node",
      "args": ["/path/to/frozo-tradingview-mcp/src/server.js"],
      "cwd": "/path/to/frozo-tradingview-mcp"
    }
  }
}
```

### 4. Connect to Claude Desktop App

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):
```json
{
  "mcpServers": {
    "tradingview": {
      "command": "node",
      "args": ["/path/to/frozo-tradingview-mcp/src/server.js"],
      "cwd": "/path/to/frozo-tradingview-mcp"
    }
  }
}
```

### 5. Verify

Ask Claude: *"Use tv_health_check to verify TradingView is connected"*

### 6. Set Up Your Profile

```
/tv-profile-setup
```

This guided interview builds `trader-profile.json` — your identity file that personalizes everything.

---

## The 5-Phase Professional Workflow

Run `/tv-pro-workflow` and the AI auto-detects the current time and executes the right phase:

### Phase 1: Pre-Market News (8:00 AM)
```
/tv-news
```
Fetches global market news via web search: US close, Asia futures, GIFT Nifty, India VIX, FII/DII data, RBI/Fed updates.

### Phase 2: Morning Prep (8:30 AM)
```
/tv-morning-prep
```
- GIFT Nifty gap estimate
- India VIX threshold check
- Expiry day detection (weekly/monthly Thursday)
- Deep scan: Daily + trading TF with all indicators
- Sector rotation heatmap (10 Indian sectors)
- Structured morning brief with bias

### Phase 3: Market Open (9:30 AM)
```
/tv-gap              # Classify gap type (Common/Breakaway/Exhaustion/Island)
/tv-opening-range    # IB analysis + open type (OD/OTD/ORR/OA) + draw levels
/tv-regime           # Market regime (Trending/Ranging/Volatile/Choppy)
```

### Phase 4: Active Trading (9:30 - 3:15 PM)
```
/tv-validate-trade   # Go/no-go checklist against YOUR rules
/tv-position-size    # F&O-aware lot sizing (NIFTY 75, BANKNIFTY 30)
/tv-dhan-execute     # Place order on Dhan (with confirmation)
/tv-session          # Live dashboard: P&L, risk budget, trade count
/tv-divergence       # NIFTY vs BANKNIFTY/VIX correlation monitor
```

### Phase 5: End of Day (3:15 PM)
```
/tv-eod-report       # Session summary + compliance audit
/tv-journal          # Auto-generate trade journal entry
/tv-journal-review   # Weekly behavioral pattern analysis
```

---

## All 32 Slash Commands

| Phase | Command | What It Does |
|-------|---------|-------------|
| **Setup** | `/tv-profile-setup` | Guided interview to build your trader profile |
| **Setup** | `/tv-layout` | Save/load multi-pane chart layouts |
| **Setup** | `/tv-telegram` | Set up Telegram bot for mobile alerts |
| **Daily** | `/tv-start-session` | One command: health check + crons + session tracker + morning prep |
| **Daily** | `/tv-pro-workflow` | Complete 5-phase professional workflow with news |
| **Pre-Market** | `/tv-news` | Global market news via web search |
| **Pre-Market** | `/tv-morning-prep` | Full morning briefing (GIFT Nifty, VIX, expiry, sectors) |
| **Pre-Market** | `/tv-sectors` | Sector rotation heatmap (10 Indian sectors) |
| **Open** | `/tv-gap` | Gap type classification |
| **Open** | `/tv-opening-range` | Initial Balance analysis + draw levels |
| **Open** | `/tv-regime` | Market regime detector |
| **Analysis** | `/tv-analyze-chart` | Full chart analysis report |
| **Analysis** | `/tv-multi-tf` | Multi-timeframe confluence (3-4 TFs, scored 1-10) |
| **Analysis** | `/tv-divergence` | Nifty vs BankNifty/VIX/USDINR divergence monitor |
| **Analysis** | `/tv-compare` | Compare current chart to a historical date visually |
| **Analysis** | `/tv-backtest-pattern` | Scan history for pattern occurrences + statistics |
| **Trading** | `/tv-validate-trade` | Go/no-go checklist with expiry + session awareness |
| **Trading** | `/tv-position-size` | F&O-aware position sizing (lot multiples) |
| **Trading** | `/tv-options` | Option strategy suggester (strikes from chart levels + VIX) |
| **Trading** | `/tv-dhan-execute` | TradingView analysis to Dhan broker execution bridge |
| **Trading** | `/tv-alert-analyze` | Instant GO/NO-GO when an alert fires (<30 sec) |
| **Trading** | `/tv-rules` | Natural language rules engine + monitoring |
| **Trading** | `/tv-similar-trades` | Find matching trades in your journal history |
| **Trading** | `/tv-session` | Live session dashboard (P&L, risk budget, time alerts) |
| **Review** | `/tv-journal` | Auto-generate trade journal entry |
| **Review** | `/tv-what-if` | "What if I held longer?" exit strategy comparison |
| **Review** | `/tv-eod-report` | End-of-day report with compliance audit |
| **Review** | `/tv-journal-review` | Weekly/monthly behavioral pattern analysis |
| **Strategy** | `/tv-strategy-report` | Backtest performance report |
| **Strategy** | `/tv-scan-symbols` | Multi-symbol screening |
| **Development** | `/tv-pine-generate` | Natural language to Pine Script indicator |
| **Practice** | `/tv-replay-coach` | Coached replay with behavioral tracking |

---

## Trader Profile

The `trader-profile.json` file defines WHO you are. Every skill adapts to it.

```bash
# Option 1: Guided interview
/tv-profile-setup

# Option 2: From template
cp trader-profile.example.json trader-profile.json
# Edit with your details
```

### What the Profile Controls

| Section | What It Affects |
|---------|----------------|
| `identity` | Name, style (scalper/intraday/swing), experience level |
| `instruments` | Primary symbols, watchlist, default timeframe |
| `risk` | Account size, risk %, max daily loss, max consecutive losses, lot sizes |
| `session` | Trading hours, no-trade zones, expiry day rules |
| `entry_rules` | Required conditions, preferred conditions, forbidden conditions |
| `exit_rules` | Stop method, target method, trailing rules, min R:R |
| `indicators` | Trusted indicators, ignored indicators, custom signal definitions |
| `behavioral_notes` | Known weaknesses, strengths, coaching tone preference |
| `telegram` | Bot token, chat ID, which alerts to send |
| `journal` | Directory, screenshot inclusion, emotion tracking |

---

## Telegram Alerts

Get trading notifications on your phone — trade entries, session warnings, morning briefs, EOD reports.

### Setup (3 minutes)

1. Message **@BotFather** on Telegram, send `/newbot`, get your bot token
2. Message your bot, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` to get your chat_id
3. Add to `trader-profile.json`:

```json
"telegram": {
  "bot_token": "YOUR_TOKEN",
  "chat_id": "YOUR_CHAT_ID"
}
```

4. Test: `/tv-telegram` or `tv telegram test`

### What Gets Sent Automatically

| Event | Telegram Message |
|-------|-----------------|
| Morning prep completes | Condensed brief with bias |
| Trade entry logged | Entry details + size |
| Trade exit logged | P&L result (WIN/LOSS) |
| 2 consecutive losses | Warning to stop |
| Session status RED | Alert: limits hit |
| Alert fires | GO/NO-GO analysis |
| EOD report | Day summary with stats |

---

## Indian Market Features

Built-in support for NSE/BSE F&O trading:

- **Expiry detection**: Auto-detects weekly (Thursday) and monthly (last Thursday) expiry
- **GIFT Nifty**: Pre-market gap estimate from GIFT Nifty futures
- **India VIX thresholds**: <13 low, 13-18 normal, 18-25 elevated, >25 high, >30 no-trade
- **F&O lot sizes**: NIFTY (75), BANKNIFTY (30), FINNIFTY (40), MIDCPNIFTY (50), SENSEX (10)
- **Session time checks**: Lunch hour avoidance, last 15 min warnings, first 5 min cooldown
- **Sector rotation**: 10 NSE sectoral indices scanned and ranked
- **Option strategies**: Strike selection based on chart levels + VIX

---

## Dhan Broker Integration

If you have the `dhan-tradehull` MCP server connected, the bridge enables:

```
Chart Analysis (TradingView) --> Validation --> Position Sizing --> Order Placement (Dhan)
```

- Setup validator says GO --> AI shows execution summary --> You confirm --> Order placed
- Never auto-executes — always requires your explicit confirmation
- Checks all session/risk/expiry rules before allowing execution

---

## CLI

Every tool is also a `tv` CLI command with JSON output:

```bash
# Profile management
tv profile view              # Show your profile summary
tv profile init              # Create from template
tv profile validate          # Check for missing fields

# Risk management
tv risk position-size --entry 22700 --stop 22650  # Uses profile defaults

# Telegram
tv telegram test             # Test connection
tv telegram send -m "msg"    # Send message
tv telegram screenshot -f chart.png -c "Setup"

# Chart operations
tv status                    # Connection check
tv quote                     # Current price
tv ohlcv --summary           # Price summary
tv screenshot                # Capture chart

# All commands
tv --help
```

---

## Scheduling

### Remote (runs even without Claude Code open)
Morning news brief is pushed to Telegram at 8:27 AM IST via scheduled remote agent.

### Local (runs during your Claude Code session)
Run `/tv-start-session` each morning — it sets up all intraday crons:

| Time | What Runs |
|------|-----------|
| 9:33 AM | Gap analysis + Opening Range |
| 9:38 AM | Market regime + Sector rotation |
| 12:03 PM | Mid-day dashboard + Divergence check |
| 3:17 PM | EOD report + Journal |
| Every 30 min | Rules monitor |

---

## 79 MCP Tools

### Chart Reading
`chart_get_state` `data_get_study_values` `quote_get` `data_get_ohlcv`

### Pine Script Graphics
`data_get_pine_lines` `data_get_pine_labels` `data_get_pine_tables` `data_get_pine_boxes`

### Chart Control
`chart_set_symbol` `chart_set_timeframe` `chart_set_type` `chart_manage_indicator` `chart_scroll_to_date` `chart_set_visible_range` `symbol_info` `symbol_search` `indicator_set_inputs` `indicator_toggle_visibility`

### Pine Script Development
`pine_set_source` `pine_smart_compile` `pine_get_errors` `pine_get_console` `pine_get_source` `pine_save` `pine_new` `pine_open` `pine_list_scripts` `pine_analyze` `pine_check`

### Replay Mode
`replay_start` `replay_step` `replay_autoplay` `replay_trade` `replay_status` `replay_stop`

### Risk Management
`risk_position_size`

### Telegram
`telegram_send` `telegram_send_screenshot` `telegram_trade_alert` `telegram_test` `telegram_status`

### Drawing & Alerts
`draw_shape` `draw_list` `draw_remove_one` `draw_clear` `draw_get_properties` `alert_create` `alert_list` `alert_delete`

### Multi-Pane & Tabs
`pane_list` `pane_set_layout` `pane_focus` `pane_set_symbol` `tab_list` `tab_new` `tab_close` `tab_switch`

### UI Automation
`ui_click` `ui_keyboard` `ui_type_text` `ui_hover` `ui_mouse_click` `ui_scroll` `ui_find_element` `ui_evaluate` `ui_open_panel` `ui_fullscreen`

### Batch & Capture
`batch_run` `capture_screenshot` `watchlist_get` `watchlist_add` `layout_list` `layout_switch` `depth_get`

### Health & Launch
`tv_health_check` `tv_launch` `tv_discover` `tv_ui_state`

---

## 30 Skills

| Category | Skill | Purpose |
|----------|-------|---------|
| Setup | `profile-setup` | Guided interview to build trader identity |
| Pre-Market | `morning-prep` | Full morning briefing with GIFT Nifty, VIX, expiry |
| Pre-Market | `sector-scan` | 10 Indian sector indices rotation heatmap |
| Open | `gap-analysis` | Gap type classification and fill probability |
| Open | `opening-range` | Initial Balance + open type classification |
| Analysis | `chart-analysis` | Full chart analysis report |
| Analysis | `multi-tf-confluence` | Multi-timeframe signal agreement scoring |
| Analysis | `regime-detector` | Trending/Ranging/Volatile/Choppy classification |
| Analysis | `divergence-monitor` | Nifty vs BankNifty/VIX/USDINR correlations |
| Analysis | `screenshot-compare` | Compare chart to historical date |
| Analysis | `pattern-backtest` | Scan history for pattern occurrences |
| Trading | `trade-setup-validator` | Go/no-go checklist with profile rules |
| Trading | `option-strategy` | Option strategy from chart bias + VIX |
| Trading | `dhan-bridge` | TradingView to Dhan broker execution |
| Trading | `alert-analyzer` | Instant analysis when alert fires |
| Trading | `rules-engine` | Natural language rules + monitoring |
| Trading | `trade-similarity` | Find similar trades in journal history |
| Trading | `session-tracker` | Live P&L dashboard and risk management |
| Review | `auto-journal` | Auto-generate trade journal entries |
| Review | `what-if-replay` | Exit strategy comparison |
| Review | `auto-report` | EOD report with compliance audit |
| Review | `journal-review` | Weekly/monthly behavioral pattern analysis |
| Strategy | `strategy-report` | Backtest performance report |
| Strategy | `multi-symbol-scan` | Batch symbol screening |
| Development | `pine-develop` | Pine Script write/compile/debug loop |
| Development | `pine-generator` | Natural language to Pine Script |
| Practice | `replay-practice` | Basic replay stepping |
| Practice | `replay-coach` | Coached replay with behavioral tracking |
| Presets | `layout-presets` | Save/load multi-pane configurations |
| Alerts | `telegram-alerts` | Telegram bot setup and notification management |

---

## Architecture

```
Claude Code / Desktop
       |
       | (stdio / MCP protocol)
       v
  MCP Server (Node.js)
       |
       | (Chrome DevTools Protocol, localhost:9222)
       v
  TradingView Desktop (Electron)
       |
  +----+----+
  |         |
Profile   Telegram     Dhan Broker
(.json)   (Bot API)    (MCP bridge)
```

**Dependencies**: `@modelcontextprotocol/sdk`, `chrome-remote-interface` (that's it)

---

## Testing

```bash
npm test              # E2E + unit tests
npm run test:unit     # Pine analysis + CLI tests (no TradingView needed)
npm run test:all      # All tests including replay
```

29 tests covering: Pine Script static analysis, server-side compilation, CLI routing, replay mode, and input sanitization.

---

## Research Context

This project explores: **how can LLM agents interact with professional trading interfaces to support human decision-making?**

Key findings:
- Context management is the primary constraint (compact defaults are critical)
- 79 tools don't confuse the agent with good instructions (CLAUDE.md decision tree)
- Pine Script development is the strongest use case for agent assistance
- Trader profile personalization dramatically improves recommendation quality
- Behavioral coaching (revenge trade detection, rule adherence tracking) is uniquely valuable

See [RESEARCH.md](RESEARCH.md) for open questions and findings.

---

## Disclaimer

This project is provided **for personal, educational, and research purposes only**.

This tool uses Chrome DevTools Protocol (CDP), a standard debugging interface built into all Chromium/Electron applications. It does not reverse engineer any proprietary protocol, connect to TradingView's servers, or bypass any access controls. The debug port must be explicitly enabled by the user.

By using this software, you acknowledge:

1. **You are solely responsible** for compliance with [TradingView's Terms of Use](https://www.tradingview.com/policies/) and all applicable laws
2. TradingView's Terms **restrict automated data collection and scraping** — this tool may conflict with those terms
3. **You assume all risk** — the authors are not responsible for account bans, legal actions, or other consequences
4. This tool **must not be used** for redistributing market data, circumventing subscriptions, automated trading using extracted data, or violating Pine Script authors' IP
5. Market data remains subject to exchange and data provider licensing terms
6. This tool accesses undocumented internal APIs that may break at any time

**Use at your own risk.** If unsure about compliance, do not use this tool.

Not affiliated with TradingView Inc. or Anthropic, PBC.

## License

MIT — see [LICENSE](LICENSE). Applies to source code only, not to TradingView's software, data, or trademarks.