# TradingView MCP

A local MCP bridge and CLI for inspecting and controlling TradingView Desktop charts, developing Pine Scripts, and practicing with chart replay.

The original [tradingview-mcp](https://github.com/tradesdontlie/tradingview-mcp) was created by [@tradesdontlie](https://github.com/tradesdontlie). This checkout adds local connection handling, launchers, and integration improvements.

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

> [!IMPORTANT]
> **Uses your TradingView account permissions.** Install TradingView Desktop and sign in with access to the charts and features you intend to use. This tool does not bypass account, subscription, or exchange-data restrictions.

> [!NOTE]
> **The MCP connection runs locally.** Some tools use TradingView endpoints for symbol search, Pine compilation, and authenticated alert management.

---

## One-Shot Setup

Paste this into **Claude Code or Codex running locally on the computer with TradingView Desktop**. The agent needs terminal and file access; a cloud-only chat cannot reach your desktop's local debug port.

```text
Set up TradingView MCP for the local client I am using (Claude Code or Codex).
Repository: https://github.com/madiver/TradingView-MCP
First read the setup guide: https://raw.githubusercontent.com/madiver/TradingView-MCP/main/SETUP_GUIDE.md

Reuse an existing checkout only after verifying it is this repository; otherwise clone that URL into a stable folder such as ~/TradingView-MCP. Do not overwrite another folder or discard local changes. Check Git and a supported Node.js version, then run npm ci in the checkout.

Follow the setup guide's instructions for my OS and this client. Reuse a working debug launcher if already configured; otherwise use the correct native Mac/Windows launcher from https://github.com/madiver/TradingView-MCP/releases/latest, or the documented Linux launch steps. Keep TradingView sign-in and save prompts under my control.

Register the local stdio server using absolute paths to Node and src/server.js. Use claude mcp add for Claude Code or codex mcp add / the Codex TOML configuration for Codex. Inspect any existing tradingview entry, preserve other servers and settings, and retain a custom local debug port if already configured. If you cannot identify the client, ask which one to configure.

Verify the client registration and run npm run tv -- status. Tell me if I need to reconnect or restart the client. After its tools are available, call tv_health_check and chart_get_state without changing my chart. Report separately whether configuration is saved and whether the live chart connection has been verified; do not claim success for checks you could not run.
```

The same prompt works without an existing checkout. Follow [SETUP_GUIDE.md](SETUP_GUIDE.md) for manual steps, Windows commands, both configuration formats, and reconnect instructions.

---

## Prerequisites

- **TradingView Desktop app**, signed in with the required chart/data permissions
- **A supported Node.js LTS: 22, 24, or 26** (`.nvmrc` selects 24)
- **Git** to clone the repository for MCP setup
- **An MCP client with local stdio support**, such as **Claude Code or Codex**, or a terminal for the CLI
- **macOS, Windows, or Linux**

---

## Quick Start

Standalone **Mac Intel, Mac Apple silicon, Windows Intel/AMD, and Windows ARM launchers** are available in [GitHub Releases](https://github.com/madiver/TradingView-MCP/releases/latest). They need TradingView Desktop, but no developer tools. See [installation and sharing instructions](launcher/RELEASING.md). Install the MCP server separately using the steps below when you want AI chart tools.

### 1. Clone and install

For a new installation, clone the public repository to a stable folder, then install the locked dependencies:

```bash
git clone https://github.com/madiver/TradingView-MCP.git
cd TradingView-MCP
npm ci
```

If you already have a checkout, verify its remote and use it without discarding local work. See [SETUP_GUIDE.md](SETUP_GUIDE.md) for home-directory and Windows examples.

### 2. Launch TradingView with CDP

TradingView must be running with the debug port enabled.

**macOS:** download the Intel or Apple silicon launcher from [Releases](https://github.com/madiver/TradingView-MCP/releases/latest), extract it, and drag **TradingView Debug.app** to Applications. Use that app from Finder or the Dock; the download needs no Python or Xcode. See [installation instructions](launcher/RELEASING.md).

To build and install from source instead:
```bash
python3 launcher/install.py
```
The source installer requires Python 3 and Xcode Command Line Tools (`swiftc`). Both versions request a graceful restart and respect save prompts. See [launcher instructions](launcher/README.md).

**Windows:** use the standalone [TradingView Debug launcher](launcher/windows/README.txt). It supports graceful restarts, verifies the connection, and can be shared without this repository. The legacy batch entry point runs the installed launcher:
```bat
scripts\launch_tv_debug.bat
```

**Linux:** start TradingView with the local debug flags. Quit any existing non-debug instance through its UI first:
```bash
/path/to/tradingview --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222
```
The legacy shell launch scripts terminate matching processes; they do not provide the native launchers' save-prompt handling. Linux chart automation has not been qualified against an installed Desktop app in this checkout.

Or use the MCP tool after setup: `"Use tv_launch to start TradingView in debug mode"`

### 3. Register the MCP server

Choose **Claude Code or Codex**, and replace the example paths with the actual absolute paths. Use `node -p "process.execPath"` to find your Node executable; a desktop client may not inherit your terminal's PATH. Register only the client you intend to use, or configure each separately if you use both.

**Claude Code** (user-scoped stdio server):

```sh
claude mcp add --scope user --transport stdio tradingview --env TV_CDP_HOST=127.0.0.1 --env TV_CDP_PORT=9222 -- "/absolute/path/to/node" "/absolute/path/to/TradingView-MCP/src/server.js"
claude mcp get tradingview
```

**Codex** (local stdio server):

```sh
codex mcp add tradingview --env TV_CDP_HOST=127.0.0.1 --env TV_CDP_PORT=9222 -- "/absolute/path/to/node" "/absolute/path/to/TradingView-MCP/src/server.js"
codex mcp get tradingview
```

Keep an existing custom port in place of `9222`. Claude Code uses `~/.claude.json` for user-scoped servers; Codex uses `~/.codex/config.toml` by default. Codex desktop/CLI/IDE clients on the same host share configuration. If the CLI is unavailable, merge the matching JSON or TOML entry from [SETUP_GUIDE.md](SETUP_GUIDE.md); do not paste JSON into Codex's TOML file. That guide also includes native Windows PowerShell examples.

Official references: [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Codex MCP](https://developers.openai.com/codex/mcp).

### 4. Verify

Check `claude mcp get tradingview` or `codex mcp get tradingview`, then use `/mcp` in the corresponding terminal client to inspect available tools. Reconnect or restart your client if needed; registration alone does not make tools available in an already-running chat.

Ask: *"Use tv_health_check and chart_get_state to verify the connection without changing my chart."* A ready chart should report `cdp_connected: true` and `api_available: true`. If the tools are not loaded yet, `npm run tv -- status` can check the local connection, but client setup remains unverified until its tools work.

---

## What This Tool Does

- **Pine Script development** — write, inject, compile, debug scripts with AI
- **Chart navigation** — change symbols, timeframes, zoom to dates, add/remove indicators
- **Visual analysis** — read indicator values, price levels, drawn levels from custom indicators
- **Draw on charts** — trend lines, horizontal levels, rectangles, text
- **Manage alerts** — create, list, delete price alerts
- **Replay practice** — step through historical bars, practice entries and exits with P&L tracking
- **Screenshots** — capture chart state
- **Multi-pane layouts** — 2x2, 3x1 grids with different symbols per pane
- **Stream data** — JSONL output from your live chart for monitoring scripts
- **CLI access** — every tool is also a `tv` command, pipe-friendly JSON output

---

## Choosing Tools

The server advertises tool-selection instructions. `AGENTS.md` and `CLAUDE.md` provide repository-specific guidance for coding agents.

| You say... | Tool sequence |
|------------|---------------|
| "What's on my chart?" | `chart_get_state` → `data_get_study_values` → `quote_get` |
| "Give me a full analysis" | `quote_get` → `data_get_study_values` → `data_get_pine_lines` → `data_get_pine_labels` → `capture_screenshot` |
| "Switch to BTCUSD daily" | `chart_set_symbol` → `chart_set_timeframe` |
| "Write a Pine Script for..." | `pine_set_source` → `pine_smart_compile` → `pine_get_errors` |
| "Start replay at March 1st" | `replay_start` → `replay_step` → `replay_trade` |
| "Set up a 4-chart grid" | `pane_set_layout` → `pane_set_symbol` |
| "Draw a level at 94200" | `draw_shape` (horizontal_line) |

---

## Tool Reference

### Chart Reading

| Tool | When to use | Output size |
|------|------------|-------------|
| `chart_get_state` | First call — get symbol, timeframe, all indicator names + IDs | ~500B |
| `data_get_study_values` | Read current RSI, MACD, BB, EMA values from all indicators | ~500B |
| `quote_get` | Get latest price, OHLC, volume | ~200B |
| `data_get_ohlcv` | Get price bars. **Use `summary: true`** for compact stats | 500B (summary) / 8KB (100 bars) |

### Custom Indicator Data (Pine Drawings)

Read `line.new()`, `label.new()`, `table.new()`, `box.new()` output from any visible Pine indicator.

| Tool | When to use |
|------|------------|
| `data_get_pine_lines` | Horizontal price levels (support/resistance, session levels) |
| `data_get_pine_labels` | Text annotations + prices ("PDH 24550", "Bias Long") |
| `data_get_pine_tables` | Data tables (session stats, analytics dashboards) |
| `data_get_pine_boxes` | Price zones as {high, low} pairs |

**Always use `study_filter`** to target a specific indicator: `study_filter: "MyIndicator"`.

### Chart Control

| Tool | What it does |
|------|-------------|
| `chart_set_symbol` | Change ticker (BTCUSD, AAPL, ES1!, NYMEX:CL1!) |
| `chart_set_timeframe` | Change resolution (1, 5, 15, 60, D, W, M) |
| `chart_set_type` | Change style (Candles, HeikinAshi, Line, Area, Renko) |
| `chart_manage_indicator` | Add/remove indicators. **Use full names**: "Relative Strength Index" not "RSI" |
| `chart_scroll_to_date` | Jump to a date (ISO: "2025-01-15") |
| `indicator_set_inputs` / `indicator_toggle_visibility` | Change indicator settings, show/hide |

### Pine Script Development

| Tool | Step |
|------|------|
| `pine_set_source` | 1. Inject code into editor |
| `pine_smart_compile` | 2. Compile with auto-detection + error check |
| `pine_get_errors` | 3. Read compilation errors if any |
| `pine_get_console` | 4. Read log.info() output |
| `pine_save` | 5. Save to TradingView cloud |
| `pine_analyze` | Offline static analysis (no chart needed) |
| `pine_check` | Server-side compile check (no chart needed) |

### Replay Mode

| Tool | Step |
|------|------|
| `replay_start` | Enter replay at a date |
| `replay_step` | Advance one bar |
| `replay_autoplay` | Auto-advance (set speed in ms) |
| `replay_trade` | Buy/sell/close positions |
| `replay_status` | Check position, P&L, date |
| `replay_stop` | Return to realtime |

### Multi-Pane, Alerts, Drawings, UI

| Tool | What it does |
|------|-------------|
| `pane_set_layout` | Change grid: `s`, `2h`, `2v`, `2x2`, `4`, `6`, `8` |
| `pane_set_symbol` | Set symbol on any pane |
| `draw_shape` | Draw horizontal_line, trend_line, rectangle, text |
| `alert_create` / `alert_list` / `alert_delete` | Manage price alerts |
| `batch_run` | Run action across multiple symbols/timeframes |
| `watchlist_get` / `watchlist_add` | Read/modify watchlist |
| `capture_screenshot` | Screenshot (regions: full, chart, strategy_tester) |
| `tv_launch` / `tv_health_check` | Launch TradingView and verify connection |

---

## Tool behavior

`quote_get` with a different symbol temporarily switches the bound chart and restores it. Strategy-report tools may open the Strategy Tester and make a hidden strategy visible; their results report that change. Alert creation/deletion changes actual TradingView alerts. Replay trades are practice actions, and the project does not place live broker/exchange orders.

Connections stay bound to their selected tab during an operation. Use `tab_follow_visible` between operations to attach to the chart currently visible; avoid switching targets during a drawing run. The default debug endpoint is `127.0.0.1:9222`. Match `TV_CDP_PORT` to any custom launcher port and keep the endpoint local.

## Tests and development

```bash
npm ci
npm run check       # JavaScript syntax checks
npm test            # offline tests and MCP startup; no Desktop chart changes
npm run test:network # opt-in Pine compilation API tests; requires internet
npm run test:e2e    # opt-in Desktop tests; changes chart state
```

Use a disposable TradingView layout for E2E tests. `npm run test:all` explicitly includes both network and Desktop suites. CI runs offline tests on Linux, macOS, and Windows with Node 22/24/26, plus launcher checks. See [CONTRIBUTING.md](CONTRIBUTING.md) for the validation matrix and .NET 10 launcher tests.

## CLI Commands

```bash
tv status                          # check connection
tv quote                           # current price
tv symbol BTCUSD                   # change symbol
tv ohlcv --summary                 # price summary
tv screenshot -r chart             # capture chart
tv pine compile                    # compile Pine Script
tv pane layout 2x2                 # 4-chart grid
tv stream quote | jq '.close'      # monitor price ticks
```

Full command list: `tv --help`

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `cdp_connected: false` | Open TradingView Debug and match the MCP port to the launcher port. |
| `ECONNREFUSED` | TradingView isn't running or port 9222 is blocked |
| MCP server missing in Claude Code | Run `claude mcp get tradingview`, inspect `/mcp` and the selected JSON scope, then reconnect/restart |
| MCP server missing in Codex | Run `codex mcp get tradingview`, inspect the matching TOML entry and local host, then reconnect/restart |
| `tv` command not found | Run `npm link` from the project directory |
| Tools return stale data | TradingView still loading — wait a few seconds |
| Pine Editor tools fail | Open Pine Editor panel first: `ui_open_panel pine-editor open` |

---

## Architecture

```
MCP Client  ←→  MCP Server (stdio)  ←→  CDP (port 9222)  ←→  TradingView Desktop (Electron)
```

- **Transport**: MCP over stdio + CLI (`tv` command)
- **Connection**: Chrome DevTools Protocol on localhost:9222
- **Local chart connection** — chart tools use CDP; symbol search, Pine compilation, and alerts can use TradingView endpoints
- **Dependencies**: MCP SDK, Chrome DevTools client, and Zod; versions are locked in `package-lock.json`

---

This checkout selectively incorporates input-handling and reliability fixes from
[upstream commit c05b8f5](https://github.com/tradesdontlie/tradingview-mcp/tree/c05b8f5755ed8e64ea242de88ddbf46aa24d56a4).
Local visible-tab selection, explicit target binding, the macOS debug launcher, and
TVLevels integration are retained. `npm run test:unit` runs the regression suite
without changing a live TradingView chart. Chart-mutating E2E tests remain separate.

## Credits

Original TradingView MCP author: [@tradesdontlie](https://github.com/tradesdontlie). The [original repository](https://github.com/tradesdontlie/tradingview-mcp) provides the foundation for this project. Its copyright and license notices are retained. See [PROVENANCE.md](PROVENANCE.md) for source lineage and the clean-history boundary.

---

## Disclaimer

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

This tool uses the Chrome DevTools Protocol (CDP), a standard debugging interface built into all Chromium-based applications. Chart operations use the locally running Desktop app; symbol search, Pine compilation, and alert management can also use TradingView endpoints. Account permissions and access controls remain applicable. The debug port must be explicitly enabled by the user via a standard Chromium command-line flag.

By using this software you agree that:

1. You are solely responsible for ensuring your use complies with [TradingView's Terms of Use](https://www.tradingview.com/policies/) and all applicable laws.
2. This tool accesses undocumented internal TradingView APIs that may change at any time.
3. This tool must not be used to redistribute, resell, or commercially exploit TradingView's market data.
4. The authors are not responsible for any account bans, suspensions, or other consequences.

**Use at your own risk.**

## License

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