tv-history MCP

Standalone historical asset-analysis MCP server backed by tvDatafeed and local timeframe-specific CSV files.

Assets are loaded dynamically. TradingView-style EXCHANGE:SYMBOL is preferred, for example RUS:MX1!. The existing SYMBOL:EXCHANGE format remains accepted for backward compatibility. A valid request triggers an initial tvDatafeed download when no local history exists for that asset and timeframe.

Install and run

cd C:\_tools\202607_tradingview_mcp\tv_history
uv sync
uv run tv-history-mcp

HTTP transport:

uv run tv-history-mcp streamable-http --host 127.0.0.1 --port 8010

#or for Tailscale IP
uv run tv-history-mcp streamable-http --host 0.0.0.0 --port 8010 

The MCP endpoint is http://127.0.0.1:8010/mcp.

Codex registration for the HTTP server:

codex mcp add tv-history --url http://127.0.0.1:8010/mcp

Or let Codex launch the stdio server:

codex mcp add tv-history -- C:\_tools\202607_tradingview_mcp\tv_history\.venv\Scripts\python.exe -m tv_history.server

Related MCP server: 0xarchive-mcp

Tool

asset_analysis(
  asset="BITSTAMP:BTCUSD",
  timeframe="1h",
  timestamp="2026-07-01T12:00:00Z"
)

When timestamp is omitted, price_data may contain the latest received non-final bar. Its is_bar_complete status uses the configured exchange delay; all derived analysis continues to use finalized bars only.

The compact execution response is the only response format and is returned by default. The response_version parameter may be omitted. Use include_indicators=true when raw indicators are needed.

asset_analysis(
  asset="BITSTAMP:BTCUSD",
  timeframe="4h",
  timestamp="2026-07-01T12:00:00Z",
  include_indicators=true
)

asset_bars(
  asset="ICEEUR:BRN1!",
  timeframe="1h",
  timestamp="2026-03-23T00:00:00Z",
  sessions=4
)

asset_bars returns OHLCV bars oldest-first. It includes an opened latest bar by default and marks each bar with is_bar_complete. Use count (1–1000) or sessions; when both are supplied, sessions wins.

asset_chart(
  asset="BITSTAMP:BTCUSD",
  timeframe="4h",
  timestamp="2026-07-01T12:00:00Z",
  days="10"
)

asset_chart returns a PNG candlestick chart with red/green bodies, wicks, and volume, plus a compact metadata block describing the asset and chart range. Use sessions instead of days to request a fixed number of trading dates; sessions wins when both are supplied. All tool errors use the same structured error object and are marked as MCP errors.

Supported timeframes are 1h, 4h, 1D, and 1W. Each timeframe is fetched directly from tvDatafeed and stored independently as 1h.csv, 4h.csv, 1D.csv, or 1W.csv. Analysis and charts read the requested timeframe file; they do not construct higher-timeframe bars from 1h.csv.

RUS daily trading-date timestamps (2026-09-07)

For assets listed in provider.rus_daily_trading_date_assets (initially RUS:MX1! and RUS:SI1!), 1D responses now label each daily bar with its inferred owning trading date at 00:00Z. This is a trading-date label, not the physical session-open time. Raw CSVs and provider timestamps remain unchanged, as do OHLCV values. 1h, 4h, and other assets retain their existing timestamps. Restart the MCP server to load this change; agent_loop.py requires no changes.

The symbol list is configurable in config.yaml:

provider:
  rus_daily_trading_date_assets:
    - "RUS:MX1!"
    - "RUS:SI1!"

Add another verified RUS symbol to this list and restart MCP to apply it. The existing setting name is retained for compatibility; it selects both daily (1D) and weekly (1W) normalization. An empty list disables this normalization; omitting the setting retains the MX1/SI1 defaults. Asset strings are canonicalized; malformed entries, other exchanges, and duplicate symbols fail configuration loading. The list selects the existing session rules; it does not automatically make those rules suitable for every stock on the exchange.

YDEX is not compatible with this profile. A direct September 7 check of 500 daily source bars found weekday opens at 04:00Z and separate weekend bars at 07:00Z: September 5, 6, and 7 are three distinct daily rows. It should retain each calendar date if a separate same-date normalization is implemented. The MX1/SI1 profile rejects its 07:00Z daily template instead of relabeling weekend prices as Monday. YDEX has therefore not been added to the list.

No exchange calendar is used. The standard UTC-hour rules are:

A following recorded daily session bounds this inference: it cannot be assigned past that successor's date. This handles recorded working Saturdays even when old intraday history is absent. Unrecognized source timestamp patterns return an error rather than being guessed.

Existing local 4h.csv data can correct or confirm the standard date. Both the daily open and its successor must be present in the 4h cache; the successor must have opened, and their aggregate open/high/low must match the daily bar. Normally all nominal four-hour intervals must end before the successor. A final session-end bar may cross that nominal boundary only when cached 1h bars cover every hour up to the boundary, a successor hourly bar exists, and the pre-boundary hourly OHLC exactly matches that final 4h bar. Post-boundary prices are not used. Missing or mismatching hourly evidence retains the standard fallback. The ending intraday Moscow date then determines ownership. Daily closes may use settlement prices, and volumes can be revised independently, so neither is a matching requirement. No additional 4h downloads are initiated. A live daily tail without a successor always keeps the standard assumption.

asset_bars includes source_timestamp, timestamp_basis, timestamp_evidence, and timestamp_ambiguous on normalized daily bars. Response metadata (timestamp_normalization, or daily_timestamp_normalization in analysis) describes the convention and evidence counts. Charts and analysis use the same normalized view. Original source opens are checked before exposing rows at a historical cutoff, so moving a morning label to midnight does not make the bar available before its source session opened.

Fallback policy: absent, incomplete, or mismatching 4h evidence retains the standard date. It is an assumption, not calendar-verified finality. Holiday ownership can remain wrong until suitable evidence exists. If fallback assigns two source rows the same date, both are retained in source order and flagged; use source_timestamp as their unique identity. In the audited cache this occurs for the February 19/22, 2021 source rows in each asset. Never deduplicate by the normalized t. No source rows are excluded to resolve these collisions.

This supplies conservative midnight completion boundaries to consumers using t + 24h. It also means the unchanged agent-loop partial-daily logic cannot reconstruct pre-Monday weekend prices from the Monday-labeled daily bar; those prices remain available in the unchanged intraday series. Source revisions and calendar-free fallback still prevent a guarantee of identical historical/live classification inputs. This change does not freeze existing episodes.

Validation: tests/test_trading_dates.py covers standard rules, holiday and working-Saturday corrections, unusable evidence, live tails, cutoff eligibility, collision preservation, and raw-key refreshes. The read-only full-cache audit is D:/PY/202607_algo_llm/agent-judge-release-h4/agent_calibrated_v19/research_execution/rus_daily_timestamp_audit.py; its September 7 report is in the adjacent rus_daily_timestamp_audit_20260907/ directory. All 3,771 MX1 and 5,032 SI1 rows and their OHLCV were preserved; daily bars, analysis, and charts passed, and both September 7 preweek contexts end on September 4. Audit files retain raw hashes and mapping provenance.

RUS weekly timestamps (2026-09-07)

Configured symbols also return 1W bars stamped Monday 00:00Z of their owning trading week. The opening daily bar is matched by raw timestamp and open price; its inferred trading date (including the local 4h correction when available) determines the Monday label. Missing or mismatching daily evidence uses the standard opening-session rule. Only existing local daily/4h caches are consulted; no auxiliary downloads or calendar lookups are introduced.

For example, raw 2026-08-29T06:00Z becomes 2026-08-31T00:00Z, and raw 2026-09-05T06:00Z becomes 2026-09-07T00:00Z. A Monday-morning source opening also becomes Monday midnight. Original source opens still gate availability. Consumers using t + 7 days <= anchor now retain the prior week exactly at Monday midnight and exclude the current week. Raw weekly OHLCV and source timestamps are preserved; this does not rebuild weekly prices from daily bars.

Weekly responses identify convention rus_weekly_trading_week_v1 and expose the same per-bar provenance fields as daily responses. Calendar-free historical fallback can produce repeated labels around exceptional holidays. Both rows remain, flagged as ambiguous; do not deduplicate by t. The full cache audit found 29 flagged rows per symbol (including propagated daily ambiguity), and no ambiguous labels in the checked August 31/September 7 weeks. Historical fallback labels are assumptions, not verified holiday ownership.

The read-only audit preserved all 780 MX1 and 1,082 SI1 weekly rows and OHLCV, verified Monday-midnight labels and both week cutoffs, and recorded raw CSV hashes in D:/PY/202607_algo_llm/agent-judge-release-h4/agent_calibrated_v19/research_execution/rus_weekly_timestamp_audit_20260907.json. Restart MCP to load the weekly change. No agent-loop change is required.

September 8 correction: the November 3, 2025 16:00Z MX1 daily source bar now maps to November 5 00:00Z, rather than the November 4 fallback. The final November 5 13:00Z 4h bar is verified against hourly bars through 15:00Z, all ending by the 16:00Z successor boundary. This applies to daily normalization and weekly opening-day evidence, uses only existing local hourly storage, and does not alter source prices or require agent-loop changes. Restart MCP to load.

An empty timeframe store requests up to 5,000 bars. A subsequent request refreshes only when its timestamp is later than the latest stored timestamp for that timeframe. The refresh size is the estimated number of missing bars plus 10 overlapping bars, capped at 5,000. New and old rows are merged by timestamp, with fresh provider values winning.

Provider failures are retried five times with a five-second wait between attempts. Attempts 1–3 use the original request capped at 5,000 bars, attempt 4 caps it at 4,000, and attempt 5 caps it at 2,000.

Every triggered provider download is appended to data/download_control.csv. The control rows contain asset, timeframe, requested_at, bars_requested, status (success or failure), and the UTC input_timestamp. Existing rows from the older schema are preserved with a blank timeframe because it cannot be inferred reliably. Requests already covered by local data do not trigger a download and are not logged.

Holiday reopening segment verification (2026-09-08)

If full-interval RUS daily O/H/L verification fails, normalization may verify only its final contiguous 4h segment after a gap of at least 28 hours between opens (at least 24 hours after the preceding nominal 4h close). The segment must start at 03/04/05/06 UTC, contain at least two consecutive 4h bars on one Moscow date, reach the next daily opening, and match daily open/high/low AND volume exactly. Existing hourly verification remains mandatory when the final 4h bar overlaps the successor opening. Settlement close differences are allowed; source OHLCV is never rewritten. Evidence is reported as four_hour_holiday_tail_ohlv_matches with _hourly_session_end when applicable. Missing/mismatching evidence retains the existing fallback; this is not a universal holiday-calendar replacement.

This corrects MX1/SI1 source 2025-12-30T16:00Z to daily 2026-01-05T00:00Z and therefore weekly 2026-01-05T00:00Z, eliminating that December 29 collision and preventing admission into January 5 pre-week context. Restart MCP to load the change; no agent-loop/adapter changes or raw-cache migration are needed.

Shared timestamp profiles v2 (2026-09-08)

provider.timestamp_profiles now explicitly maps MX1/SI1 to moex_futures, GC1/NQ1 to cme_overnight, BRN1 to ice_brent, and BTCUSD to utc_calendar. This mapping supersedes the legacy RUS list when present; {} disables all profiles, while removing the key restores the legacy RUS behavior. Unknown assets remain raw and are NOT certified for execution. Add symbols only after checking compatibility with a profile. CME uses America/Chicago and ICE Europe/London for initial hour-based dates; this handles DST rather than fixing an opening UTC hour.

Daily output t is trading-date midnight UTC; weekly output t is Monday midnight. source_timestamp preserves the actual source stamp. Intraday times and all raw storage/prices remain unchanged. Intraday evidence verifies/corrects daily ownership; absent or mismatching evidence retains the profile's standard date. Weekly verification checks contributing daily ownership, dates inside the labelled week and aggregate O/H/L; failed checks are reported, not excluded. Daily settlement closes/weekly volume revisions are not forced to match. Bitcoin uses its UTC calendar convention without requiring an intraday cache for daily labels; weekly validation still requires daily evidence.

Operator-selected policy: retain all eligible bars. Missing intraday history, mismatching prices or no successor does not remove a bar. Normal evening opens advance to the next weekday; normal morning opens retain the date. Matching intraday evidence overrides this fallback. Duplicate labels are preserved and flagged, never merged. unverified_rows and unverified_source_timestamps report verification failures over available history at the cutoff, not just the tail. Unknown opening patterns are explicitly listed in unrecognized_source_timestamps. The loop ignores ambiguity/completeness flags: retaining fallback bars means unresolved holiday ownership can still cause future-data leakage. This policy preserves history; it is not a universal all-history causality guarantee.

Restart MCP to activate. Re-run affected research before comparing with artifacts created under the old timestamp policy. Raw caches need no migration; consumer caches keyed by returned timestamps must distinguish v2. No engine/adapter code or saved episodes are modified.

Profile timezone correction (2026-09-08): intraday-confirmed ending dates use Europe/Moscow for MOEX, America/Chicago for CME, Europe/London for Brent and UTC for Bitcoin. Using Moscow for every profile incorrectly advanced Brent weekday labels when the last 4h opening was 21:00 UTC. Fixed in code; restart required.

Evening-range fallback (2026-09-08)

Profiles now use local-time ranges including the start and excluding midnight: MOEX Europe/Moscow 18:00–24:00; CME America/Chicago 16:00–24:00; Brent Europe/London 22:00–24:00. Opening minutes within the range are accepted. Evening openings advance to the next weekday labelled at 00:00 UTC; daytime openings retain their local date. MOEX's separate observed 06:00 UTC additional session rule remains. Bitcoin retains its UTC calendar convention. Matching 4h (and required hourly) evidence can override the standard date. Missing or failed verification keeps the fallback even when it is a holiday, per operator choice. No bars are dropped. Weekly dates use Monday of the derived daily date; this corrects the nine legacy GC Sunday21UTC openings in 1983 to the following Monday. The range definitions live in timestamp_profiles.py::SESSION_PROFILES. Restart MCP to load this change. Raw storage, OHLCV, loop and adapter are unchanged.

Exchange/product-specific 4h holiday verification (2026-09-08)

timestamp_profiles.py::SESSION_PROFILES now owns timezone, evening range, holiday-tail session shape and volume policy together. MOEX retains daytime 03–06UTC reopening, one local date and exact O/H/L/volume. CME allows an evening opening in its local range followed by the next local date, bounded to at most 25 elapsed hours (DST allowance). Brent permits that overnight shape or a morning opening before05 local on one date. Bitcoin disables holiday-tail reinterpretation. All tail checks retain the post-gap requirement, contiguous4h intervals, at least two bars, next-daily boundary and existing hourly validation for shortened ends. CME/Brent require matching O/H/L; volume disagreement is reported in evidence as four_hour_holiday_tail_ohl_matches_volume_differs, not rewritten or used to reject the ownership match. MOEX's stronger exact-volume requirement remains unchanged. Failed verification still retains standard fallback per operator instruction.

Stored cases verified: GC July7,2025 / June22,2026 / July6,2026; NQ July7,2025 / June22,2026; MX/SI January5,2026. Both daily and weekly labels belong to the proper Monday and fail that Monday's pre-week admission filter. Restart MCP to activate; this is not a guarantee for other unmatched historical cases.