TradingView-MCP

Let an AI inspect your TradingView Desktop app and help analyze your charts.

100+ MCP tools for chart inspection and control, indicators, Pine Script, backtesting, market research, falsification audits, point-in-time evidence, and cross-market analysis.

Register this server with an AI agent such as Claude Code, Codex, or Antigravity, and the agent can read the chart you are currently viewing. Your signed-in account, saved layouts, and purchased custom indicators remain available in the Desktop app.

What You Can Do

Example requests:

• "Analyze the current chart." -> combine the chart image, candles, and indicator values.

• "Read this indicator's signals." -> retrieve BUY/SELL labels and support/resistance values.

• "Assess the market on both the daily and four-hour timeframes." -> retrieve multiple-timeframe evidence without moving the chart.

• "Find Japanese stocks with RSI below 30." -> search the market scanner.

• "Check every symbol in my watchlist." -> retrieve quotes for the complete list.

Related MCP server: TradingView MCP Bridge

How It Works

TradingView Desktop is an Electron application. When launched with its debugging endpoint enabled, an external program can inspect the chart. This MCP server provides that bridge.

AI agent <-> tradingview-mcp <-> TradingView Desktop (your chart)
                              <-> TradingView public APIs (quotes and scanner)

Requirements

• macOS and TradingView Desktop (the free plan is sufficient)

• Node.js 22 or later (check with node --version; Node 20 is EOL)

• An AI agent such as Claude Code, Codex, or Antigravity

Setup in Three Steps

Step 1: Install the Server

In a terminal:

git clone https://github.com/tedorigawa001/TradingView-MCP.git
cd TradingView-MCP
npm install
npm run build

Step 2: Launch TradingView in Debug Mode

Important: The AI cannot inspect TradingView when it is launched normally from the app icon. If TradingView is running, quit it with Cmd+Q, then run:

open -a TradingView --args --remote-debugging-port=9222

To avoid typing the full command each time, add an alias and launch it with tv:

echo 'alias tv="open -a TradingView --args --remote-debugging-port=9222"' >> ~/.zshrc
source ~/.zshrc

Step 3: Register the MCP Server

Choose the instructions for your agent. Replace /path/to/TradingView-MCP with the cloned repository path (run pwd from the repository to find it).

Run one command:

claude mcp add tradingview -- node /path/to/TradingView-MCP/build/index.js

Alternatively, open Claude Code in this repository. The bundled .mcp.json registers the server automatically.

Verify by running /mcp in Claude Code and confirming that tradingview appears.

Option 1 - add it with the CLI:

codex mcp add tradingview -- node /path/to/TradingView-MCP/build/index.js

Option 2 - add it directly to ~/.codex/config.toml:

[mcp_servers.tradingview]
command = "node"
args = ["/path/to/TradingView-MCP/build/index.js"]

Verify by running /mcp in Codex and confirming that tradingview appears.

Create or update ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "tradingview": {
      "command": "node",
      "args": ["/path/to/TradingView-MCP/build/index.js"]
    }
  }
}

From the IDE, open the same file from ... -> MCP Servers -> Manage MCP Servers -> View raw config in the upper-right corner of the agent panel. Saving reloads it automatically.

Try It

With TradingView running in debug mode, ask your AI agent:

Analyze the current chart.

The agent can combine tools such as get_chart_context (what is displayed), get_chart_screenshot (visual evidence), and get_ohlcv (numeric evidence).

Tools (101 Total)

The AI selects the appropriate tools automatically; you do not need to memorize them.

Read charts

Operate charts

Data outside the chart

Market context and evaluation

First-seen collection CLI

npm run collect:first-seen -- --cot-symbol OANDA:EURUSD --cot-symbol OANDA:XAUUSD collects COT, the U.S. 10-year real yield, and all-contract GC open interest from the CME Daily Bulletin into append-only first-seen logs. npm run coverage:first-seen reports collection days, revisions, and first/last observation dates for COT, real yield, futures OI, and policy rates as JSON. Set scheduled COT symbols with TRADINGVIEW_MCP_COLLECTION_COT_SYMBOLS=OANDA:EURUSD,OANDA:USDJPY,OANDA:XAUUSD, or pass --cot-symbol per symbol as the launchd example does. Naming them matters: with neither, the CLI collects only its two-symbol default, and a symbol added once by hand stops being collected without any error.

npm run collect:research-hypotheses appends a run record to ~/.tradingview-mcp/research-collection-heartbeats.jsonl whether or not a hypothesis fired, because the evidence file only grows on a closed event and the frozen hypotheses produce roughly one every ten days. Without it a quiet week and a dead collector are the same record, and the second cannot be filled in afterwards. Override the path with TRADINGVIEW_MCP_RESEARCH_COLLECTION_HEARTBEAT_PATH. Coverage reports run count, maximum gap in hours, latest-run age, chart-restoration failures, and per-hypothesis attempts against events.

npm run collect:policy-rates reads ECONOMICS:*INTR for USD/EUR/JPY/GBP/AUD/NZD/CAD/CHF in sequence and appends changes to ~/.tradingview-mcp/policy-rate-first-seen.jsonl. Every run that successfully acquires all eight currencies, persists values, and restores the chart is also recorded in ~/.tradingview-mcp/policy-rate-collection-heartbeats.jsonl, whether or not a value changed. This lets the primary test verify first-seen values and collection continuity separately. Override the heartbeat path with TRADINGVIEW_MCP_POLICY_RATE_COLLECTION_HEARTBEAT_PATH. Coverage reports distinct run days, same-day reruns, maximum business-day age between runs, intervals beyond the frozen five-day limit, and latest-run age. The script uses the same cross-process chart lock as the MCP server, passes the approved --confirm-chart-switch, and verifies restoration after every currency. Because TradingView's 00:00 UTC bar is not a release timestamp, available_at is conservatively set to 00:00 UTC on the next business day. This reproducible boundary prevents meeting-day lookahead but is not the actual publication time.

npm run collect:official-policy-rates writes to a separate exploration-only official-history store. Sources include the ECB Deposit Facility SDMX CSV; BoC Valet V39079; the exclusive date splice of FRED DFEDTAR with the midpoint of DFEDTARL/DFEDTARU from 2008-12-16; RBA F1 FIRMMCRTD, joining the official legacy XLS (1990-08-02 through 2010-12-31) to the current daily CSV from 2011-01-04; the SNB policy rate and legacy Libor target-range midpoint; and a frozen BoJ meeting-decision manifest. BoJ periods without a single short-rate target are stored as value: null so an obsolete rate is not carried forward. Effective market rates are not substituted for policy targets. Unchanged observations are reduced to change points, while raw snapshots retain original row count and first/last dates to distinguish missing data from unchanged values. Raw bodies retain raw_sha256, retrieval time, and Last-Modified vintage and are stored owner-only at ~/.tradingview-mcp/policy-rate-official-raw/<sha256>.raw; reused hashes are revalidated. This is revised history and must not support prospective/OOS evidence, the primary test, or adoption decisions.

npm run collect:fx-history -- --from 2022-01-01T00:00:00.000Z --to 2026-01-01T00:00:00.000Z reads OANDA_FX_HISTORY_ACCOUNT_ID and OANDA_FX_HISTORY_ACCESS_TOKEN only from the environment and retrieves confirmed OANDA v20 EUR_USD midpoint M15 candles. Choose practice (default) or live; credentials and account IDs are never written to stdout, manifests, or raw evidence. Requests are paged at no more than 4,000 bars and timeouts, 429s, and 5xx responses are retried up to three times per page. Successful pages are archived before checkpoints are appended to ~/.tradingview-mcp/fx-history-m15-manifest.jsonl.checkpoints, so rerunning the same range revalidates archived raw data and resumes from the first incomplete page. Raw responses are stored owner-only by content hash under ~/.tradingview-mcp/fx-history-raw/<sha256>.raw. The manifest records range, retrieval time, raw and normalized hashes, counts, first/last bars, boundary duplicates, and weekday discontinuities. Equal duplicates are removed; conflicting duplicates stop the run. This revised official history is not a first-seen series and currently supports exploratory long-run CPI/NFP/FOMC research only, not existing OOS adoption gates.

On macOS, register com.tradingview-mcp.policy-rate-collection for weekdays at 10:45 JST without RunAtLoad, so login and MCP restart do not immediately move the chart. External first-seen collection runs at 10:30 and 22:30 JST on weekdays to create two observation windows for preliminary-to-final CME OI revisions; this schedule does not guarantee the final publication. Both jobs share the chart-operation lock, so they wait or fail during MCP use rather than restoring another process's temporary symbol.

Macro surprise forward collection

npm run coverage:macro-surprise -- --events CPI_ARTIFACT --events NFP_ARTIFACT --events FOMC_ARTIFACT --confirm-local-import reconciles official release artifacts with local first-seen evidence and separately reports pre-collection events, missed forward consensus/actual values, releases still inside the 15-minute actual-capture window, and evaluable surprises. Revised official history does not prove that historical consensus was known, so events_before_collection is not a gap. A nonzero missing_forward_consensus or missing_forward_actual blocks the directional study.

macOS examples are provided for daily consensus collection, five-minute actual collection, and daily coverage checks. Actual collection fetches official documents only within 15 minutes of release. Set TRADINGVIEW_MCP_TRADING_ECONOMICS_API_KEY in the launchd environment before loading the consensus job. The examples reference real 2016-2026 artifacts; update all three paths to the same artifact set each year. Keep the mapping JSON private and outside Git.

Event-study falsification audit CLI

npm run audit:event-studies -- --config fvg-audit.json calibrates a frozen event-study definition against synthetic nulls. Defaults are 400 replications per model, 5,000 bars, nominal alpha 5%, and three folds; white noise, regime-switching volatility, and bid-ask bounce are reported separately. The audit never accesses TradingView, the network, or local journals. For a quick smoke test, override with --model white_noise --replications 20 --bars 1200.

The configuration contains only the study definition and candidate rule. For example:

{
  "study": {
    "type": "fvg_retest",
    "definition": {
      "symbol": "SYNTH:FVG_RETEST",
      "timeframe": "15",
      "minimumGapBps": 10,
      "retestWithinBars": 24,
      "minImpulseBodyRatio": 0.5,
      "requireBoundaryHold": true,
      "horizons": [1, 4, 8],
      "targetReturnBps": 20,
      "minimumEvents": 30,
      "eventLimit": 0,
      "confidenceLevel": 0.95,
      "configurationTrials": 1,
      "regime": null,
      "branchFilter": "bearish"
    }
  },
  "candidate": {
    "branch": "fvg_retest_bearish",
    "horizon": 4,
    "minimumEvents": 30,
    "minimumFoldEvents": 5,
    "folds": 3
  }
}

Each model's Wilson interval is used to assess whether its candidate rate exceeds nominal alpha. This does not prove profitability or future edge; it audits how often the adoption rule fires on a series with no signal.

For an event-aftershock-retest audit, provide eventSchedule instead of real economic-event times. firstBar, everyBars, and maximumEvents define a relative exogenous schedule within each synthetic series; they do not predict, substitute for, or reproduce real events.

Periodic research-hypothesis collection

npm run collect:research-hypotheses serially collects three prospective hypotheses: XAUUSD M15 bearish FVG x trend_down, daily EURUSD/U.S. 10-year nonconfirmation, and EURUSD M50 lower-wick x trend_down. It refuses to run during Bar Replay, temporarily switches the two existing panes, and restores their original symbols and timeframes after success or failure. It does not modify orders, alerts, Pine scripts, or studies.

Only aggregates are stored in ~/.tradingview-mcp/research-collection.jsonl, and a record is appended only when the primary horizon has at least one closed event. Startup verifies that all three hypothesis IDs are preregistered in the research journal. The MCP server and CLI share one owner-only chart-operation lock. In stdout, collection_status describes execution and research_status describes evidence sufficiency; either being partial makes the top-level status partial. For scheduled macOS operation, copy and load the launchd examples for research hypotheses, external first-seen collection, and policy rates. TradingView must be running with CDP enabled. The research example runs hourly to reduce visible chart interference.

Required history is frozen per job: 5,000 bars for FVG, 1,000 per series for the daily rate nonconfirmation, and 500 for the M50 feature study. Missing bars are loaded on the same temporary chart, and coverage records initial, added, and final counts, provider capacity, and sufficiency. If the requirement cannot be met, insufficient_loaded_history stops analysis and evidence recording; short history is never presented as complete evidence.

get_execution_snapshot first reads bid, ask, lp_time, session state, real-time load state, and price increment from open TradingView charts. lp_time is the last-price time in the same quote snapshot, not an exchange timestamp for each bid/ask. A chart quote is ready only when it is no more than five seconds old by default and is streaming, in an active session, and real-time loaded. If the symbol is not open, the tool falls back to the scanner. The scanner has no market-side bid/ask timestamp or session calendar, so receipt time is never substituted for market time; the fallback is ready only after observing a bid/ask change within the default 1.2-second window. No movement returns wait. This does not guarantee fillability or liquidity and does not change accounts, orders, or charts.

compute_position_size returns instrument units, not broker-specific lots. Supply quantity_step, minimum_quantity, and where needed maximum_quantity and contract_multiplier according to the execution venue. Loss includes Entry-to-Stop distance plus explicit round-trip cost such as compute_round_trip_cost.total_price_per_unit, converted to account currency. When quote and account currencies differ, size is returned only with a fresh account-currency/quote-currency rate, symbol, and observation time. The tool does not connect to an account, read balances, place orders, or persist positions.

Real-yield first-seen history is appended to ~/.tradingview-mcp/real-yield-first-seen.jsonl by default; override it with TRADINGVIEW_MCP_REAL_YIELD_HISTORY_PATH. Historical rows fetched on first startup are not backdated to past publication times and become eligible for backtests only after the time they were actually stored.

Futures-OI first-seen history is appended to ~/.tradingview-mcp/futures-open-interest-first-seen-v3.jsonl by default; override it with TRADINGVIEW_MCP_FUTURES_OI_HISTORY_PATH. Chart-derived OI is recorded when read by get_futures_flow_context, and official CME all-contract GC OI is recorded by get_cme_gold_open_interest and the collection CLI. Chart proxies and official CME values remain separate. Pre-collection vintages cannot be reconstructed: historical values downloaded today are revised values, not necessarily what was visible at the time.

If a process crashes while writing history and leaves a .lock, history access stops rather than deleting it automatically. Confirm that no other TradingView-MCP process is running before deleting only the adjacent .lock file.

The evaluation CLI uses the snapshot's request_completed_at as evaluation time and binds evaluation_context.real_yield_10y only to a version first seen by that time. It never falls back to the current value or a later revision.

npm run evaluate -- --log evaluation.jsonl --snapshot snapshot.json

Use --real-yield-history PATH for an isolated store. If the snapshot has no completion time, supply canonical UTC with --as-of 2026-07-01T12:00:00.000Z. An --as-of later than request_completed_at is rejected as lookahead. Missing history is not imputed and records point_in_time_status=blocked; corrupt history or lock failure prevents the snapshot itself from being appended.

Pine scripts (user-owned only)

To overlay analysis on the chart, save the template once with save_pine_script, then use ensure_analysis_overlay to place, update, and obtain its study_id. An existing current version is reused without writing, so each analysis does not create another script or study. If a legacy migration preview returns contextBindingRequired:true, confirmation binds that analysis to the currently verified symbol/timeframe. Expired analyses remain visible as EXPIRED. Template defaults are not treated as analysis and return unconfigured. After application, status rechecks inputs, current-price geometry, and drawings; a chart that differs from the stored context returns stale_context and trusted:false.

Current-price geometry does not establish historical hit order. evaluate_analysis_overlay_outcome evaluates closed OHLC after the analysis, excluding both the analysis-time bar and the forming bar. After Entry, an optional Confirmation must occur on a later bar; Invalidation before confirmation cancels the setup. Once active, Target 1 versus Stop is evaluated first-hit. This does not prove fills or P&L: touching opposing levels in one bar or opening across a terminal returns ambiguous. If history is short, load more or request a shorter evaluation_timeframe. The latter keeps the expected_timeframe overlay contract, temporarily switches only the selected chart, verifies symbol/resolution/bar evidence, and restores it. If chartState.restored is false, inspect currentTimeframe and restore manually. Daily and weekly aliases are supported; calendar-month M is not_evaluable because its duration varies.

The analysis journal defaults to ~/.tradingview-mcp/analysis-journal.jsonl; override it with TRADINGVIEW_MCP_ANALYSIS_JOURNAL_PATH. apply_analysis_overlay(confirm:true) records the definition after verified readback, while outcome evaluation appends only with explicit record:true. The same ID and definition are idempotent; reusing an ID for a different definition or assigning conflicting completed labels is rejected. A definition conflict requires a new analysis_id, not a retry. If only journal writing fails, the application/evaluation result remains available with journal.recorded:false and a warning. Calibration uses only target_before_stop=1 and stop_before_target=0; all other outcomes are counted by exclusion reason.

The journal reclaims a .lock only when it is older than 60 seconds and its recorded owner PID no longer exists. A live, unverifiable, or recent lock is never stolen, and the timeout names its path. Before manually deleting that lock, confirm that no TradingView-MCP process is using it.

This enables a read -> modify -> save -> backtest improvement loop:

Read the BushidoScalp source, implement a change that reduces false signals, save it, backtest it on USDJPY 4H, and compare it with the original.

Backtesting

Troubleshooting

Security

See docs/security-review.md for the full review. At minimum:

• While the debug port is open, any program on the same machine can control the signed-in TradingView session. Launch in debug mode only while using the AI, use normal mode otherwise, and do not use this setup on a shared machine.

• The server is read-oriented. Writes are limited to non-destructive user-owned Pine versioning, adding/changing/removing verified owned studies, creating expiring alerts from audited analysis, and starting/stepping/stopping Bar Replay. Confirmation gates protect the relevant tools. Orders, Replay Trading, Replay autoplay, modification/resume/deletion of existing alerts, webhooks, watchlist changes, and Pine-library deletion are intentionally absent.

• get_chart_screenshot sends everything visible on screen, including watchlists, to the AI provider.

Development

Testing

npm test                   # Node unit tests + Bookmap Java tests
npm run test:integration   # Integration tests (requires the app in debug mode)
npm run test:e2e           # Real-app E2E over MCP stdio (configuration below)

npm test does not require TradingView. With the complete Bookmap SDK installed locally, it also runs the Collector, signal-engine, and Bookmap-adapter Java tests. With no or partial SDK, it builds and tests only the SDK-free FlowSignalEngine for Java 17 and explicitly skips adapter tests.

On pull requests and pushes, GitHub Actions runs npm test on Node.js 22 and 24, including the SDK-free signal engine. A separate npm audit job rejects high or critical vulnerabilities.

Integration tests temporarily change symbols and timeframes and restore them afterward.

For walk-forward E2E, set TRADINGVIEW_WALK_FORWARD_E2E_CONFIG to JSON matching the current chart and saved strategy. Do not include confirm; the test owns confirmation.

TRADINGVIEW_WALK_FORWARD_E2E_CONFIG='{"expected_symbol":"OANDA:USDJPY","expected_timeframe":"240","candidates":[{"pine_id":"USER;YOUR_PINE_ID","inputs":[{"id":"in_20","value":false}]},{"pine_id":"USER;YOUR_PINE_ID","inputs":[{"id":"in_20","value":true}]}],"folds":[{"fold_id":"f1","train_from":"2025-03-01T00:00:00.000Z","train_to":"2025-09-01T00:00:00.000Z","test_from":"2025-09-02T00:00:00.000Z","test_to":"2025-12-01T00:00:00.000Z"},{"fold_id":"f2","train_from":"2025-03-01T00:00:00.000Z","train_to":"2025-12-01T00:00:00.000Z","test_from":"2025-12-02T00:00:00.000Z","test_to":"2026-03-01T00:00:00.000Z"}],"mode":"anchored","embargo_bars":1,"minimum_train_trades":5,"minimum_test_trades":3,"selection_metric":"expectancy","max_runtime_seconds":180}' npm run test:e2e

For analysis-alert E2E, set TRADINGVIEW_ANALYSIS_ALERTS_E2E_CONFIG to match the installed analysis overlay.

TRADINGVIEW_ANALYSIS_ALERTS_E2E_CONFIG='{"pine_id":"USER;YOUR_PINE_ID","expected_symbol":"OANDA:USDJPY","expected_timeframe":"4H","analysis_id":"USDJPY-20260724-001","confirm":false}' npm run test:e2e

For Fair Value Gap Retest event-study E2E, set TRADINGVIEW_FVG_RETEST_E2E_CONFIG to match the chart.

TRADINGVIEW_FVG_RETEST_E2E_CONFIG='{"expected_symbol":"OANDA:EURUSD","expected_timeframe":"60","count":5000,"condition":{"type":"fair_value_gap_retest","minimum_gap_bps":10,"retest_within_bars":24,"min_impulse_body_ratio":0.5,"require_boundary_hold":true},"horizons":[1,2,4,8],"target_return_bps":20,"minimum_events":1,"event_limit":50,"confidence_level":0.95,"configuration_trials":1}' npm run test:e2e

Futures-flow E2E requires open_interest_study_id, open_interest_plot_title, and an open_interest_scope that freezes the value's meaning in TRADINGVIEW_FUTURES_FLOW_E2E_CONFIG. Scope must be paired with explicit OI data or study selection and cannot accompany pure autodetection, which reads only TradingView's official front-month Open Interest study. Otherwise a front-month value could be mislabeled as an aggregate. Missing OI fails explicitly so a broken first-seen collector cannot pass silently. The test redirects collection to a temporary file and does not contaminate production logs.

TRADINGVIEW_FUTURES_FLOW_E2E_CONFIG='{"target_symbol":"OANDA:XAUUSD","futures_chart_index":1,"expected_futures_symbol":"COMEX_DL:GC1!","count":250,"observation_limit":0,"minimum_observations":100,"cot_weeks":1,"open_interest_study_id":"YOUR_STUDY_ID","open_interest_plot_title":"Total OI","open_interest_scope":"all_months_aggregated"}' npm run test:e2e

E2E verifies rejection of incorrect chart binding, deterministic dry-runs, train-only selection, suppression of unselected candidates' OOS results, protocol validation, ledger stress, seeded bootstrap, real alert creation and ownership naming, bounded responses, and complete chart restoration. Missing configuration causes a skip.

Repository Layout

• src/ - TypeScript source

  • cdp.ts - CDP connection, evaluation, and screenshots

  • tradingview.ts - in-page TradingView API layer

  • scanner.ts - public scanner API client

  • server.ts - dependency-injected MCP tool definitions

  • index.ts - stdio entry point

• test/unit/ - unit tests with mock CDP and scanner

• test/e2e/ - configuration-driven E2E from MCP stdio to the real app

• test/smoke.mjs - integration smoke test against the real app

• build/ - ignored TypeScript output

• bookmap-addon/ - Java Bookmap add-on. FlowSignalEngine and FlowSignalMarker import nothing from the Bookmap SDK and are built and tested everywhere, including CI; FlowCollector and FlowSignalResearch need the locally installed SDK and are skipped without it. dist/ is ignored

• docs/ - design and research documentation

Documentation

• docs/STRATEGY.md - overall strategy and progress

• docs/phase0-findings.md / phase3 / phase4 / phase5 - internal API research

• docs/security-review.md - security review

• docs/BACKLOG.md - future improvements