# tradingview-mcp

MCP server giving AI agents a TradingView-centric trading toolkit: screener queries, historical FX data, and — as milestones land — SMC/ICT pattern scanning, chart rendering with markup, backtesting, Pine tooling, and a bundle of companion Agent Skills.

> **AI agents:** to install and verify this MCP for a human, follow [`AGENT_SETUP.md`](AGENT_SETUP.md) top to bottom (prerequisites → `uv sync` → `scripts/healthcheck.py` → register both servers → smoke tests → report).

**Not affiliated with TradingView, Inc.** "TradingView", "Pine Script" and "Lightweight Charts" are trademarks of TradingView, Inc.

## Status

M0-M7 complete, M8 landed (part B awaits one live run): server boots with `public`/`data` defaults; opt-in toolsets for SMC scanning, chart rendering, backtesting, FX Replay journal sync, TradingView-account data (`session`), Pine compile, Desktop CDP (35 tools: app launcher, screenshots, API-driven symbol/timeframe/viewport navigation, drawing on the live chart, reading and configuring the user's own indicators — plot values, Pine-drawn FVG/OB zones incl. compact levels/zones, input changes with read-back —, Strategy Tester report, bar replay, and the Pine Editor: get/set source, compile-on-chart with error markers, save, open saved scripts; M8: scored chart-tab binding, generic UI find/click, level-tag checks on the chart's own bars, workspace preparation, surgical byte-verified Pine edits, own-copy protection, and `tv_desktop_pine_build_and_backtest` - one call from source to Strategy Tester report), declarative strategies, and a hybrid mode beside the official TradingView MCP. M7 ports the six mechanisms worth having from the community bridge `tradesdontlie/tradingview-mcp` (MIT) into this server's driver — landmines in `docs/PLAN.md`. Ships a `tv` CLI (every tool = a subcommand emitting JSON), 11 companion skills, and a validated Claude Code plugin manifest. Open items: M1's trust gate still awaits the owner's real hand-labeled SMC setups; webhook receiver, MCP Apps, and the sandboxed Python strategy escape hatch are deferred. Roadmap: `docs/PLAN.md`.

## Install as a Claude Code plugin

```
/plugin marketplace add Miha21222/tradingview-mcp
/plugin install tradingview-mcp@tradingview-mcp-marketplace
```

The install registers **two** servers: this one (`tradingview`, stdio) and the official TradingView MCP (`mcp-tradingview`, `https://mcp.tradingview.com/mcp`). It prompts for optional credentials (OANDA practice key, TradingView `sessionid`) and operator settings (`TV_TOOLSETS`, `TV_READ_ONLY`, ...). Plugin default is `TV_TOOLSETS=hybrid`; set it to `default` (= `public,data`) for a zero-account setup that does not need the official server. Requires [uv](https://docs.astral.sh/uv/) on PATH.

## Hybrid with the official TradingView MCP

TradingView ships an official MCP (public beta, needs an Essential+ plan, OAuth via `/mcp`). It covers quotes, screener, symbol search, news, economic/earnings/dividend calendars, fundamentals, filings, price alerts and watchlists — and nothing else: no charts, indicators, Pine, drawings, replay, backtests or desktop access; bars delayed 15+ minutes; no history paging beyond the last 5000 bars; no broker-CFD symbols in its screener.

This project is built to run **next to it**, not instead of it:

| Job | Server |
|---|---|
| quotes, screener, search, news, calendars, fundamentals, alerts, watchlists | official `mcp-tradingview` |
| deep/free OHLCV history, realtime session feed, SMC/ICT scans, chart rendering, backtests, strategies, Pine compile, journal, TradingView Desktop (CDP) | this server, `TV_TOOLSETS=hybrid` (+ `session`, `desktop` as opt-ins) |

`hybrid` = `data,scan,chart,backtest,pine,journal,strategy,calendar`: it drops the `public` toolset (the official screener replaces it) and keeps `tv_setup_doctor`, which now registers regardless of toolsets. The `tradingview-hybrid` skill holds the per-job routing table and the official beta's verified limits. Users without a qualifying TradingView plan keep `TV_TOOLSETS=default,...` and ignore the official entry — the two servers are independent.

## Quick start

```powershell
uv sync
uv run python -m tvmcp --check    # list registered tools
uv run python -m tvmcp            # run on stdio
uv run tv --check                 # CLI: list tools
uv run tv tv_data_get_bars '{"symbol":"EURUSD","count":10}'   # CLI: call any tool -> JSON
```

The opt-in `chart` toolset renders via headless Chromium; run `uv run playwright install chromium` once if you enable it. Enable opt-in toolsets via `TV_TOOLSETS=default,scan,chart,backtest,journal`.

Claude Code: the repo's `.mcp.json` registers both servers automatically when you trust the project (`tradingview` with `TV_TOOLSETS=hybrid`, plus the official `mcp-tradingview`).

## Configuration (env vars)

| Var | Default | Meaning |
|---|---|---|
| `TV_TOOLSETS` | `default` (= `public,data`) | Comma list; `all` enables everything; `hybrid` = `data,scan,chart,backtest,pine,journal,strategy,calendar` (pairs with the official TradingView MCP, see above). Opt-ins: `scan` (SMC scanning + session levels), `chart` (PNG rendering), `backtest`, `journal`, `pine` (compile/typecheck), `strategy` (declarative YAML specs), `calendar` (economic events, exchange holidays, futures rollover), `session` (TV-account data, ToS risk), `desktop` (CDP to TradingView Desktop, ToS risk) |
| `TV_READ_ONLY` | off | `1` = write-capable tools never register (wins over everything) |
| `TV_CACHE_DIR` | `~/.tvmcp/cache` | Parquet OHLCV cache |
| `TV_CHART_DIR` | `~/.tvmcp/charts` | Rendered PNG output (managed, collision-safe filenames) |
| `TV_JOURNAL_DIR` | `~/.tvmcp/journal` | journal watch-folder for `tv_journal_scan` / `tv_journal_parse` / `tv_journal_load` (`tv_risk_guard` also takes a full path) |
| `TV_STRATEGY_DIR` | `~/.tvmcp/strategies` | YAML strategy specs for `tv_strategy_list` / `tv_strategy_run` |
| `TV_SESSIONID` | — | Your TradingView `sessionid` cookie gates the opt-in `session` toolset (ToS risk; see below). Live fetch works: the cookie is exchanged for a websocket JWT and fed to tvdatafeed-enhanced |
| `TV_CDP_URL` | `http://127.0.0.1:9223` | CDP address of TradingView Desktop for the opt-in `desktop` toolset (start the app with `tv_desktop_launch` or `scripts/start-tv-desktop.ps1`; port **9223** on purpose — another CDP app usually owns 9222 and Chromium skips a busy port silently) |
| `TV_DESKTOP_EXE` | auto | Explicit `TradingView.exe` path for `tv_desktop_launch` when auto-discovery (Store package, `%LOCALAPPDATA%\Programs`) fails |
| `TV_MAX_BARS` | `5000` | Hard cap on bars per response |
| `OANDA_API_KEY` | — | Free practice-account key enables the OANDA provider |
| `OANDA_ENV` | `practice` | `practice` or `live` |

Run `uv run tv tv_setup_doctor` to check every prerequisite - each broken check returns the exact fix command. For a full install check in one command (Python/uv/Node/Chromium/server/doctor/MCP registration): `uv run python scripts/healthcheck.py` (`--json` for machines).

## TradingView Terms of Service

The default toolsets use no TradingView account: the `public` toolset talks to TradingView's public scanner endpoint, and market data comes from Dukascopy/OANDA. TradingView's ToS prohibits automated data collection and non-display use of its data; the optional `session` and `desktop` toolsets (off by default) interact with **your own** TradingView account/desktop app at **your own risk** — enabling them is your explicit choice and may violate TradingView's ToS and risk account restrictions. Both print a ToS/ban warning to stderr on first use. This project is for personal research/education.

## License

MIT — see [LICENSE](LICENSE). Not affiliated with TradingView, Inc.; protected/invite-only Pine scripts remain their authors' property — the study tools read only the rendered output of indicators on your own chart, never their source.