Skip to main content
Glama
Futures MCP

Futures MCP

Futures MCP

CI Python MCP

An MCP server that lets Claude look at the futures market: fetch OHLCV bars with relative volume, capture a TradingView chart framed on an exact trading-day window, detect whether a range setup formed, and return the chart with the range drawn on it.

Ask Claude: "Did gold set up a range on H1 over the three days to July 7?" It calls get_range_chart and answers with the verdict, the levels and this chart:

Range chart for GC1! H1, 3 trading days to 2026-07-07

Two completed ranges were found. Each has support/resistance, numbered rejections in the order they happened, and the time the first one broke. Everything was drawn on a live TradingView screenshot, whose axes were read by OCR so the boxes land on the right prices and bars.

Tools

Tool

What it returns

Typical time

get_futures_bars

OHLCV bars for N trading days with Relative Volume (volume / SMA14), its zone, the session tag of each bar, per-day summaries

< 2 s (cached)

capture_chart

PNG of the TradingView chart framed on exactly that window, plus the saved path

20–40 s

analyze_range

Verdict COMPLETED / NOT_COMPLETED / NO_RANGE, with each structure's support, resistance, rejections and break time

2–5 s

get_range_chart

The chart with the detected range drawn on it, plus the same report

30–50 s

get_trade_plan

For each detected range: direction, entry order and level, stop and what it is anchored to, R-multiple targets, position size and the exit rules

2–5 s

run_backtest

Walk-forward replay of the detector and the rules over past dates: every order, fill and exit, with win rate, R, P&L, drawdown and profit factor for the strategy's own exit and for 1R/2R/3R

~1 min per month

Also:

  • Resources: futures://symbols lists the supported symbols; futures://status reports the capture mode and whether the detector, the trading rules and OCR are available.

  • Prompts: range_check is a ready-made "check this symbol for a range" workflow; trade_plan continues it into the trade.

Every tool has a typed output schema (structuredContent) and read-only annotations. The long-running tools report progress.

Inline chart (MCP Apps). capture_chart and get_range_chart link a small HTML view (ui://futures-mcp/chart.html). Hosts that support MCP Apps, such as Claude Desktop, render the chart with its verdict and levels directly in the chat. Other hosts ignore it and still get the image and JSON.

Related MCP server: TradingView MCP Jackson

How it works

flowchart LR
    C[Claude Code / Desktop] <-- stdio --> S[server.py<br/>tools · resources · prompt]
    S --> SV[service.py]
    SV --> B[data/bars.py<br/>tvDatafeed + disk cache]
    SV --> T[capture/tradingview.py<br/>async Playwright]
    SV --> P[ranges/pipeline.py]
    P --> D[(private detector<br/>not in repo)]
    SV --> R[trading/rules.py<br/>loader + arithmetic guard]
    R --> E[(private trade rules<br/>not in repo)]
    SV --> BT[trading/backtest.py<br/>walk-forward replay]
    BT --> P
    BT --> R
    SV --> O[ranges/overlay.py<br/>OCR calibration + drawing]
    B --> TV1((TradingView<br/>data))
    T --> TV2((TradingView<br/>chart))
  1. One window everywhere. timewindow.window_utc(end_date, days) defines the trading-day window. The bar fetch, the screenshot (framed through TradingView's Go to → Custom range) and the scan all use it, so the bars and the chart describe exactly the same span.

  2. Bars and screenshot fetched concurrently in get_range_chart (an anyio task group). A shared Chromium page stays warm between calls; captures are serialised because the chart is one piece of UI state.

  3. Detection runs the private detector over the window's 2- and 3-day sub-windows, dedupes the hits, drops ranges contained in a wider one, and numbers the rejections.

  4. Calibration. Tesseract reads the price and time axis labels, and a least-squares fit maps price to pixels and time to pixels. If the fit is loose (RMS ≥ 1 px), or the window's high/low would fall outside the price pane, nothing is drawn and the tool returns the clean screenshot with a warning. The verdict is unaffected either way.

  5. Chart settings are forced to match the data: the axis timezone is set to UTC+5, and back-adjustment for contract rolls (B-ADJ) is turned off for the shot. If a saved layout had B-ADJ on, it is restored afterwards.

Setup

Requirements: Python 3.11+, Tesseract (on Windows the default C:\Program Files\Tesseract-OCR install is found automatically).

conda create -n futures_mcp python=3.12 -y
conda activate futures_mcp
pip install -e ".[dev]"
pip install "tvdatafeed @ git+https://github.com/stefanomorni/fork-tvdatafeed.git"
playwright install chromium

Playwright version: if playwright install cannot download the latest Chromium build (CDN timeouts), pin Playwright to match a Chromium you already have. For example, pip install playwright==1.58.0 uses Chromium build 1208.

Copy .env.example to .env if you want to change anything. All settings are optional.

Capture modes

  • Anonymous (default). TradingView's public chart. No account needed.

  • Session. Set TRADINGVIEW_SESSION_ID (your sessionid cookie) and TRADINGVIEW_URL (your saved layout). Captures then use your own layout, indicators and colours. Keep the cookie in .env, which is git-ignored.

Each chart request can also pick its mode: capture_chart and get_range_chart take an optional mode (anonymous or session), so "show it on my layout" uses your layout for that one request. When a request doesn't pick one, the server uses FUTURES_MCP_DEFAULT_MODE. If that's unset, it uses session when a cookie is set and anonymous otherwise. Set FUTURES_MCP_DEFAULT_MODE=anonymous to keep the public chart as the default while your layout is available on request.

The range detector is private

The detection rules are proprietary and are not in this repository. At runtime the server imports range_screener_v6.py from FUTURES_MCP_DETECTOR_DIR (default ./private, which is git-ignored). The contract it must meet is documented in ranges/detector.py.

Without the detector, get_futures_bars and capture_chart work normally. The two range tools return a clear error straight away, before spending any time in the browser.

To try the range tools without the private rules, point the server at the toy example detector in examples/detector/:

FUTURES_MCP_DETECTOR_DIR=examples/detector

It meets the same contract with deliberately naive logic: the box is the first day's high/low, and 4 alternating edge touches count as complete. Its results are not the ones shown above. CI uses it to run the range pipeline end to end.

So are the trading rules

get_trade_plan answers the next question — what is the trade on this range? — and the rules that answer it are private in the same way. At runtime the server imports entry_rules.py from FUTURES_MCP_RULES_DIR (default: the detector folder). The contract is documented in trading/rules.py: a module exposing RULES_VERSION and plan(bars, structure, account), and optionally simulate(bars, plan, structure, placed_idx, exit) for backtests.

Whatever the rules return, the server re-checks before it leaves the process: the stop must be on the correct side of the entry, risk_points must equal |entry − stop|, every target must sit exactly its R multiple away, and the size must clear the minimum. A plan that fails any of those is an error, not a trade. No level or size in the output is ever produced by a language model — the tool computes them and the model may only report them.

Sizing comes from the account settings: FUTURES_MCP_ACCOUNT_EQUITY (default 100000), FUTURES_MCP_RISK_PCT (default 1) and FUTURES_MCP_CONTRACT. Levels are always read on the continuous future (GC1!), but positions are sized in the micro contract by default (MGC, $10 per point), which gets much closer to the risk budget than one standard GC ($100 per point). Set FUTURES_MCP_CONTRACT=standard to size in GC.

A toy set of rules lives in examples/rules/ — last rejection, market entry at its close, stop at that bar's extreme — so the tool can be run end to end from a clean checkout:

FUTURES_MCP_DETECTOR_DIR=examples/detector FUTURES_MCP_RULES_DIR=examples/rules

It is wiring, not a strategy. CI uses it the same way it uses the toy detector.

Backtesting

run_backtest answers would this have worked? without hindsight. At every H1 bar in the period, trading/backtest.py cuts the window the live tool would have seen at that moment, runs the detector and the rules on it, and places an order only on the bar where the signal first appears. The rules' own simulate then replays that order on the bars that follow. The backtest module decides nothing about fills or exits; it schedules signals, enforces the portfolio constraints and counts:

  • One signal per range. The sliding window renumbers the same range as it moves, so later signals on an overlapping range are ignored.

  • One trade at a time. A signal is skipped while an order rests or a trade is open.

  • Stale signals are counted, not traded. Sometimes a detector recognises a structure only after the order would already have filled or been cancelled.

  • Worst case on ambiguous bars. A bar that touches both the stop and the target counts as the stop, and is flagged.

  • Roll gaps are flagged. Continuous contracts jump at a roll; trades spanning one are marked.

No commissions or slippage are modelled yet.

Connect it to Claude

Claude Code (plugin)

The repo is also a Claude Code plugin marketplace. Install the plugin once and the server is available in every session:

claude plugin marketplace add usamahassan965/futures-mcp
claude plugin install futures-mcp@futures-mcp

The plugin runs ${FUTURES_MCP_PYTHON:-python} -m futures_mcp. Point it at the environment you installed into by adding this to ~/.claude/settings.json:

{ "env": { "FUTURES_MCP_PYTHON": "C:/Users/<you>/miniconda3/envs/futures_mcp/python.exe" } }

Claude Code starts servers from whatever folder a session is in, so put your settings in the per-user file ~/.futures-mcp/.env (same keys as .env.example), using absolute paths for FUTURES_MCP_DATA_DIR and FUTURES_MCP_DETECTOR_DIR. Then ask "Is GC setting up a range on H1?".

Without the plugin:

claude mcp add futures -s user -- C:/Users/<you>/miniconda3/envs/futures_mcp/python.exe -m futures_mcp

Claude Desktop

Claude Desktop also starts servers from its own working directory: use ~/.futures-mcp/.env as above, or give absolute paths in the config. Edit %APPDATA%\Claude\claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "futures": {
      "command": "C:/Users/<you>/miniconda3/envs/futures_mcp/python.exe",
      "args": ["-m", "futures_mcp"],
      "env": {
        "FUTURES_MCP_DATA_DIR": "C:/Users/<you>/futures-mcp/data",
        "FUTURES_MCP_DETECTOR_DIR": "C:/Users/<you>/futures-mcp/private"
      }
    }
  }
}

Both work on a Claude Pro subscription. The server runs locally over stdio, so no API key is needed.

MCP Inspector

npx @modelcontextprotocol/inspector python -m futures_mcp

Development

pytest        # unit + golden + in-memory MCP protocol tests
ruff check .
mypy
  • Golden tests. Three recorded GC windows (COMPLETED, NOT_COMPLETED, NO_RANGE) in tests/fixtures/:

    • Re-scanning them must reproduce the recorded structures.

    • Re-drawing them must reproduce the recorded marked charts pixel for pixel.

  • Protocol tests. An in-memory mcp.Client runs against the real server with only the network edges faked, i.e. the bar feed and the browser. They cover schemas, argument validation, error mapping, progress, images and structured output.

  • CI runs on Ubuntu with Python 3.11 and 3.12. Tests that need the private detector are skipped there; the toy detector test still runs the range pipeline.

Scope and limits

  • Symbols: GC1! (COMEX gold). Adding a symbol is one line in symbols.py.

  • Position sizing assumes one account and one instrument's point value; it does not know your broker, margin or fees.

  • Timeframes: bars and charts on H1/H4; range detection on H1, where it is calibrated.

  • Backtests are limited by how much H1 history TradingView returns (about six months) and to 120 calendar days per run. They exclude costs.

  • Times are shown in UTC+5 (the chart axis) and UTC.

  • Not financial advice. This is an analysis tool.

License

MIT

Available Tools

4 tools
analyze_rangeAnalyze range setupA
Read-onlyIdempotent

Detect a range in the window. Verdict: COMPLETED (a range met every rule), NOT_COMPLETED (a range is forming but not yet confirmed), or NO_RANGE. Each structure lists support, resistance, its numbered rejections and, if price has left it, when it broke.

Inputs: days, symbol, end_date, timeframe. Returns: symbol, summary, verdict, timeframe, +6 more

capture_chartCapture TradingView chartA
Read-onlyIdempotent

Screenshot of the TradingView chart framed on exactly the trading-day window. Takes 20-40 seconds.

Inputs: days, mode, symbol, end_date, +1 more. Returns: mode, path, warnings, window_utc

get_futures_barsGet futures barsA
Read-onlyIdempotent

OHLCV bars for a trading-day window, with Relative Volume (volume/SMA14), its zone, the session each bar belongs to, and per-day summaries.

Inputs: days, symbol, end_date, timeframe, +1 more. Returns: bars, days, n_bars, symbol, +8 more

get_range_chartRange chartA
Read-onlyIdempotent

The TradingView chart for the window with the detected range drawn on it (support/resistance box, numbered rejections, caption), plus the report. Takes 30-50 seconds.

Inputs: days, mode, symbol, end_date, +1 more. Returns: mode, path, drawn, report, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a clear primary purpose: retrieving bar data, performing range analysis, and capturing chart images. The only potential confusion is between capture_chart and get_range_chart, but the descriptions make clear that one is a raw screenshot while the other includes the detected range and report.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: get_futures_bars, analyze_range, capture_chart, get_range_chart. The naming style is uniform and predictable, with no mixing of conventions.

    Tool Count4/5

    Four tools is somewhat lean, but appropriate for a focused futures charting and range-analysis workflow. Each tool fills a distinct step in the process, and the small count keeps the server manageable.

    Completeness4/5

    The server covers the core workflow of retrieving bars, detecting a range, and viewing charts. Minor gaps exist, such as no obvious tool for listing available futures instruments or configuring window parameters, but these do not severely block the intended use case.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to control and read from the TradingView Desktop app, providing automated morning briefs, chart analysis, Pine Script development, and replay mode.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to pull multi-timeframe Binance kline data, compute Wyckoff/VSA/GANN context, manage trading rules and journals, and optionally reconcile real positions, fills, and PnL from read-only Binance, Bybit, or OKX accounts.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to look up futures prop firm rules with each rule's verification status and cited source, run 217 tested technical indicators and candlestick patterns, and compute Setup Odds for intraday setups on the user's own bars, all through read-only tools that need no account or API key.
      10
      11
      23 npm
      MIT