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 or Windows 10/11 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

Publishing from source additionally requires a JDK because prepublishOnly runs the complete Node.js and Bookmap add-on test suites before npm accepts a release. npm users do not need Java.

Setup in Three Steps

Step 1: Install the Server

In a terminal:

npm install --global bushido-tradingview-mcp

The installed command is tradingview-mcp. You normally do not run it by itself; the AI agent starts it as an MCP stdio server. Node.js is the only requirement; the Java add-on in this repository is not part of the package.

Step 2: Launch TradingView in Debug Mode

Important: The AI cannot inspect TradingView when it is launched normally from the app icon. Quit the running app first, then use the command for your operating system.

macOS:

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

Windows PowerShell, when the app execution alias is available:

$tv = (Get-Command TradingView.exe).Source
Start-Process -FilePath $tv -ArgumentList "--remote-debugging-port=9222"

The source checkout also provides scripts\windows\start-tradingview.ps1. If the alias is not on PATH, pass the script -TradingViewExecutable "C:\path\to\TradingView.exe". See the Windows support guide for Bookmap, CI, filesystem, and scheduled-collection details. In Windows MCP configuration files, use npx.cmd instead of npx when the client does not resolve npm command shims.

Step 3: Register the MCP Server

Choose the instructions for your agent. The examples use npx, so a global installation is optional and the agent can launch the published package directly.

Run one command:

claude mcp add tradingview -- npx -y bushido-tradingview-mcp

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

Option 1 - add it with the CLI:

codex mcp add tradingview -- npx -y bushido-tradingview-mcp

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

[mcp_servers.tradingview]
command = "npx"
args = ["-y", "bushido-tradingview-mcp"]

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

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

{
  "mcpServers": {
    "tradingview": {
      "command": "npx",
      "args": ["-y", "bushido-tradingview-mcp"]
    }
  }
}

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 (132 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. A source that was fetched but not recorded in its first-seen log (a write that failed, or a latest real-yield value that is missing, invalid or future-dated) counts as an error: the run is partial, exits non-zero, and records a partial heartbeat, which the health check reports.

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 health:collections checks the scheduled-collection heartbeat logs without opening TradingView. Policy-rate collection is stale when it did not complete on the current business day; hourly research collection is stale after two hours. First-seen collection is checked against its latest expected weekday 10:30 or 22:30 JST run, and a completed but partial source run is unhealthy. A latest heartbeat stamped more than a minute after the check read its log, by a clock that ran ahead and was then set back, reads as fresh while its log refuses every later heartbeat until the clock reaches it: each collector's coverage reports it as latest_in_future, and the check reports policy_rate_clock_ahead, research_clock_ahead or first_seen_clock_ahead (its age in hours, negative, rounded away from zero to 0.01 hour), is stale, and its notification asks to check the system clock. Setting the clock right does not clear such a block: the log keeps refusing every record stamped before its latest until the clock reaches that stamp, and the collector stamped its data logs with the same clock, so the notification names the repair of every store the collector writes (the first-seen collection: first-seen-heartbeat, cot, real-yield, futures-open-interest; the policy-rate collection: policy-rate-heartbeat, policy-rate). Once the clock is right, tradingview-mcp-repair-first-seen --store <store> (npm run repair:first-seen -- --store ... from a checkout) reads the store's log as the store reads it, taking no lock, and prints which tail of records is stamped more than a minute after the clock now, and anything an interrupted repair left (a temporary file, a sidecar whose records the log still holds, a lock whose process is gone); it lists earlier repairs' sidecars apart, changes nothing, and a store with nothing ahead says so. With --apply it takes every lock of the store, never waiting on one while holding another (between tries it waits under a quarter of a second, close to how often collectors poll a lock, and tries the busy lock first, within the store's lock wait), moves exactly that tail, byte for byte, to a new owner-only sidecar <log>.ahead-<time>.jsonl and rewrites the log without it, so the next record is recorded (at the first moved sequence). It refuses when nothing is stamped ahead, when the log does not read (a dry run says to run again, as a collector may have been appending), or when anything else is odd. The stores it repairs are the three heartbeats, cot, policy-rate, real-yield, futures-open-interest (CME gold open interest), official-policy-rate (its history and raw snapshot logs), macro-surprise, and one instrument's FX history run log, manifest and page checkpoints together (fx-history --instrument ...). The real-yield log's sequences are cited by evaluation logs and the FX history's by exports already written, which the command cannot find, so there --apply also needs --force; for the FX history, a kept collection or run that needs a record being moved is refused unless --recollect is given, which moves it too, with the records after it in its log, and lists in collect_again the ranges to collect again, so that each is recorded anew. A lock that names no process (the macro-surprise store's) is never reported as a killed run's: while it is younger than the minute after which the store's own writer takes it over, --apply waits for it and says its holder cannot be told, so it must not be removed while anything may run; once older, --apply takes it over as that writer would. SIGINT, SIGTERM or SIGHUP stops --apply at its next step that can stop (a lock being taken is taken and then released), releases every lock, prints what was done, the summary on stdout and why it stopped on stderr, and ends by that signal; a second signal ends it at once. A repair killed outright (SIGKILL, power loss) can leave a sidecar, a .<log>.repair-<id>.tmp file and the store's lock: the next dry run reports them, the lock must then be removed by hand once no collector, server or repair is running (its process is gone), and the next --apply uses the sidecar instead of writing a second one and removes the temporary file. A repair of several logs that stops part-way says which logs it rewrote; running it again finishes it. The research journals that refuse a record stamped before their latest (research trials, research period usage, forward period declarations, forecast losses, risk backtests, backtest slices, realized covariance) are not repaired: their records are research decisions, cited by sequence elsewhere, and moving them would rewrite that history. If the clock was ahead when one was written, wait until the clock passes the stamp; if it is far ahead, stop the MCP server, keep a copy of the journal, check that no other record cites the sequences of the lines stamped ahead (they are always its last lines), remove those lines, keeping each remaining line ending in a newline, and note in your research record why. A heartbeat recorded while the check waited for its log, or less than a minute ahead, is not reported. Missing or malformed evidence fails closed. Use --scope research, --scope policy-rate, or --scope first-seen to read and assess only one collector. The command emits one JSON result, exits nonzero when stale, and stays notification-free by default. On macOS, --notify sends a local notification only for stale, partial, or failed checks; it never includes market data.

For a repository-location-independent launchd setup, install the package globally (npm install -g bushido-tradingview-mcp) and replace the placeholders in the examples: /ABSOLUTE/PATH/TO/node with the output of command -v node, /ABSOLUTE/PATH/TO/node_modules with npm root -g, /ABSOLUTE/PATH/TO/TradingView-MCP with a built checkout (for the examples that still run from one), and YOUR_USERNAME with your macOS user. launchd expands neither ~ nor environment variables. The research health agent runs hourly on all seven days, so a Friday-night outage is detected within the two-hour threshold. The first-seen health agent runs 45 minutes after each collection window. The separate policy-rate health agent runs at 11:15 JST on weekdays, after the 10:45 collector. These agents and the first-seen collector do not use WorkingDirectory; moving the source repository does not break the installed jobs.

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; Bank of England Bank Rate IUDBEDR; 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. Each collector also hands the store every date its files give a valid rate for. When a later download shows no change on a date it observed where a change point is stored, the store appends a withdrawn record naming the file, so the revised series and the latest value drop the change while the earlier version stays in the log. A date a download leaves out or blank is not judged, nor is any date outside it or after the retrieval day: what is stored there is kept, and the store rebuilds the series from the observed rates and those kept change points, so a change across a missing row or a row that only repeats the rate held before it is told correctly. The frozen BoJ manifest withdraws nothing. A store holding withdrawn records cannot be read by 0.1.26 or earlier, which refuse the unknown status, so do not collect into a store that an older installation still reads. 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 midpoint M15 candles of one instrument: --instrument takes EUR_USD (the default), USD_JPY, GBP_USD, AUD_USD, NZD_USD, USD_CAD, USD_CHF, AUD_NZD or XAU_USD. EUR_USD keeps its manifest, ~/.tradingview-mcp/fx-history-m15-manifest.jsonl (or TRADINGVIEW_MCP_FX_HISTORY_MANIFEST_PATH), and its checkpoints; every other instrument has its own beside them, named by inserting the instrument before a .jsonl suffix (fx-history-m15-manifest.USD_JPY.jsonl) or appending it to a path without one, each with its own .checkpoints. So the EUR_USD files, and earlier versions that read only them, are unchanged. A configured path must name a file, not a directory. All instruments share the content-addressed raw archive, and a response that names another instrument or granularity is refused. 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 the instrument's checkpoints (~/.tradingview-mcp/fx-history-m15-manifest.jsonl.checkpoints for EUR_USD), so rerunning the same range revalidates archived raw data and fetches only the pages without a final checkpoint. A page is checkpointed only once it is final, meaning every candle it returned is complete and it was read at least one candle (15 minutes) after its end. A page with a candle still forming, or with time still to come, is archived but fetched again by the next run of the same range, and unfinished_pages counts such pages. A page that 0.1.27 or earlier checkpointed before it was final (judged by when the checkpoint was written) is fetched again, and the new checkpoint names the earlier one it replaces (supersedes_sequence); the earlier checkpoint and its raw response are kept. 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 (for XAU_USD these include its daily trading break). 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. tradingview-mcp-export-fx-history (npm run export:fx-history) writes recorded collections, rebuilt from the archived raw responses and verified against their manifest records, to a new file of bars or a tradingview-mcp-import-bar-series input, and with --all --split writes a whole record over 1,000,000 bars in parts; see FX history export. Every collection run is also recorded in the instrument's run log beside its manifest, identical content included. tradingview-mcp-collect-fx-daily (npm run collect:fx-daily -- --instrument EUR_USD ...) collects the instruments it names each night over the sessions of the last ten weekdays (--lookback-weekdays) up to the last candle closed a minute ago, and tradingview-mcp-health --scope fx-history --instrument ... checks that the last daily run before the latest weekday 08:00 New York deadline finished after 17:15 the evening before and covered the previous weekday's session; see daily FX history collection and its launchd examples.

On Windows, scripts\windows\register-collection-tasks.ps1 registers the research, first-seen and policy-rate jobs as Scheduled Tasks for the interactive user; see the Windows support guide. Its time parameters are local Windows wall-clock times and default to this project's JST schedule; pass the documented local equivalents on machines in another time zone. The Windows first-seen task explicitly collects EURUSD, USDJPY, and XAUUSD. 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. The report is a view as of its run time: only evidence first seen by then counts, as in the store's eligibility check, so a value seen later neither fills an event nor starts collection. 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. These three macro-surprise jobs have no Windows registration script yet - register-collection-tasks.ps1 covers research, first-seen and policy rates only - so on Windows they must be scheduled by hand or run manually.

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. On Windows, run scripts\windows\register-collection-tasks.ps1 -TaskKind research. 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.

History stores and their outputs are opened without following symbolic links (0.1.44): every history log, the research collection output (--output-path or TRADINGVIEW_MCP_RESEARCH_COLLECTION_PATH) and the evaluation log (--log) must name the file itself. A symbolic link there is refused with a message that names the file it leads to; give that path instead.

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. Without a terminal, a result is final (no_terminal_event, not_activated or expired_without_confirmation) only once the closed bars reach the expiry, or a forming bar runs past it (evidence.expiryCoveredBy names which); before that it is incomplete (history_ends_before_expiry) and evaluate_due_analyses rechecks it, so a symbol that stops trading before the expiry stays incomplete. Bars alone cannot show that a missing bar was a market closure, so time without bars inside the window makes a result incomplete (gap_in_evaluation_window) when it has no terminal or would be decided after the gap; a result decided before the first gap stands, and a gap found while the history is still short is reported as a gap. Between two bars, or before a next bar that starts by the expiry, a gap is half a bar or more for bars of up to two hours, and a bar less an hour for longer bars, which daylight saving can move by an hour; with no bar by the expiry, it is room for a window bar before it (a whole one for bars of up to two hours). The gaps are in evidence.gaps (the first 10; evidence.gapCount counts all). A gap result, or an ongoing one flagged gap_in_evaluation_window, reports only an entry or confirmation before the first gap, and a result without a terminal over a gap has no excursion metrics. A window across a weekend, a daily or lunch break, or a thin symbol's bars without trades therefore does not complete automatically. evaluate_due_analyses takes evaluated results that stayed open (ambiguous or incomplete), and analyses whose last evaluation failed since their last recorded outcome, after the analyses that just became due and the ongoing ones, so they do not crowd them out; it groups each analysis by the outcome recorded last, so an ongoing result that stays the latest on its evidence does not hold a front place. Within each group the analysis looked at longest ago goes first, except that in the front group an analysis whose window has closed comes before an active one: an evaluation that finds the result already recorded, or fails, records no outcome but is noted in an attempt log beside the journal (<journal>.attempts.jsonl, with the previous segment in <journal>.attempts.1.jsonl, 4 MiB each), so results that do not resolve take turns. Each group with candidates gets at least one slot while the limit allows, so the front group filling every run does not keep the others waiting. The preview shows each candidate's orderGroup, recentOutcome, lastSeenAt and lastAttempt, and attemptLog says whether the log could be read (partial names a segment it could not read); what cannot be read is left out of the order. An ambiguous or gapped result whose history reached the expiry comes out the same on every recheck with the same bars, so it is listed as skipped (open_result_fixed_for_timeframe) unless the run evaluates on another timeframe than its record (evaluation_timeframe, or else the analysis timeframe) or sets include_fixed (for bars changed by the chart's session or adjustment settings, or a backfill). A result whose history does not reach back to the analysis (history_incomplete) only falls further behind with time, so it is listed as skipped (history_short_fixed_for_request) unless the run loads more history (load_more_bars) or inspects more bars (count) than the run that recorded it, evaluates on another timeframe than its record or sets include_fixed. A recheck with more history or on another timeframe is recorded even when it repeats an earlier result, so the next run with the same request skips it again. A result without a terminal that an earlier version (0.1.21 or before) recorded complete without evidence through its expiry gives way to what is recorded after it: evaluate_due_analyses rechecks it (legacy_complete_recheck), after the analyses that just became due and the other open results, and the best ranked of the evaluations recorded after it becomes the latest, a terminal found later included; evaluations recorded before it stay below it, and another earlier-version complete of a different label still conflicts with it. Until replaced, such records are counted (legacyCompleteWithoutCoverage in the evaluate_due_analyses preview, and legacy.completeWithoutCoverage in calibration and in each performance group), as are target or stop results from before the gap check (legacy.includedWithoutGapCheck), which are included as they are. If history does not reach back to the analysis, load more, or request a longer evaluation_timeframe (the same number of bars reaches further back) whose bars still fit inside the analysis window. 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, except that a completed label from this version recorded after such an earlier-version complete replaces it. 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

Concurrent history writers

Shared first-seen/heartbeat/research journals wait up to 30 seconds for a cross-process lock by default. Set TV_MCP_HISTORY_LOCK_WAIT_MS to an integer from 100 to 120000 in each MCP/collector process environment to override it; restart processes after changing it. Invalid values fail at store construction. This setting applies to AppendOnlyFirstSeenLog, not every lock in the project. Timeouts include the lock path and HISTORY_LOCK_TIMEOUT error code internally. They do not discard evidence, skip fsync or steal another writer's lock. Reduce overlapping jobs or investigate storage latency if timeouts continue. Stale-lock recovery remains manual after confirming no writer is active. The budget bounds contention retries, not an unresponsive filesystem syscall, whole collection run or time queued inside the same process. A longer wait does not guarantee fairness or cure sustained overload.

One exception: the forward period declarations journal waits at most 2 seconds, in-process queue included, whatever this setting says. The period usage check, preflight and record paths take it while holding the ledger's lock, and a stale declarations lock must not hold the ledger for 30 seconds. A timeout there fails the check and the preflight, but a record is still appended. See failures and recovery.

Security

To report a vulnerability, see SECURITY.md (GitHub private vulnerability reporting). 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

Generate comparison-ready local evidence with npm run generate:research-evidence -- --input /absolute/config.json --confirm-local-read. This hashes explicit files and records the current Node environment without executing research code. See evidence generation for scope, limits and optional private output.

Rerun a fixed saved-ledger summary with npm run reproduce:research -- --input /absolute/config.json --output /absolute/new-report.json --confirm-local-read. The installed npm command is tradingview-mcp-reproduce with the same arguments. See local reproduction; this does not rerun a strategy or authorize OOS use.

From Source

The published package provides the MCP server only. Every npm run command in this document - the collectors, the coverage reports, the studies and the audits

• is a script in this repository and needs a clone:

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

Opening Claude Code in the clone registers the server from the bundled .mcp.json, which runs build/index.js from the repository rather than the published package. That is what you want while developing: it picks up your build, not the last release.

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.

Publishing

prepublishOnly runs npm test, which includes the Bookmap Java tests, so publishing requires a JDK that supports --release 17 even though the published package contains no Java. That is deliberate: a release should not go out on a suite that was skipped. The Bookmap SDK itself is not needed - without it the Java step builds and tests the SDK-free engine and marker and skips the adapters.

prepack runs build:package (tsc --sourceMap false) rather than build, and files is limited to build/**/*.js. Source maps would otherwise be about half the package while pointing at src/ files it does not ship.

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

• SECURITY.md - security policy and how to report a vulnerability

• docs/security-review.md - security review

• docs/BACKLOG.md - future improvements