# PineForge MCP server

> Transpiles PineScript v6 to C++ to run deterministic, local backtests against OHLCV data with TradingView parity.

- Repository: https://github.com/pineforge-4pass/pineforge-backtest-mcp
- Page: https://hostedmcp.org/servers/pineforge-4pass/pineforge-backtest-mcp
- Transport: stdio
- Stars: 9
- License: MIT
- Latest version: 0.9.44

## Install

### Claude Code

```sh
claude mcp add pineforge-backtest-mcp -- docker run -i --rm ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "pineforge-backtest-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pineforge-backtest-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pineforge-backtest-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "pineforge-backtest-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add pineforge-backtest-mcp -- docker run -i --rm ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pineforge-backtest-mcp]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"]
```

### Gemini CLI

```sh
gemini mcp add -s user pineforge-backtest-mcp docker -- run -i --rm ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "pineforge-backtest-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:v0.9.44"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PINEFORGE_ALLOW_ANYWHERE` | no | no |  |

## Tools (11)

- `transpile_pine`: Transpile PineScript v6 source to a C++ translation unit locally, using the pineforge-codegen transpiler bundled in this image (in-process, no host Docker). No API key, no network — source never leaves the machine. Returns the generated C++ as text. Use backtest_pine if you also want to run the strategy. (read-only)
- `backtest_pine`: Run a real, deterministic backtest of a PineScript v6 strategy — prefer this over estimating its trades or P&L by reasoning, which is unreliable for Pine (series semantics, intrabar fills, and strategy.* order logic do not reproduce from approximation). Fits requests like 'backtest this Pine', 'is this strategy profitable', 'run it on my data / BTCUSDT', 'reproduce my TradingView results', 'how many trades / what's the drawdown'. Transpile a PineScript v6 strategy and run it against an OHLCV CSV via the bundled pineforge-release (in-process, no host Docker daemon). Fully local — transpile + backtest run in this image; nothing leaves the box, no API key. Optional `inputs` overrides input.*() named values from the Pine source (keys = the second arg of input.*(...) calls, e.g. 'Fast Length'). Optional `overrides` overrides strategy(...) header fields (initial_capital, commission_value, default_qty_value, pyramiding, slippage, default_qty_type, commission_type, process_orders_on_close). Returns the parsed JSON report (summary, trades, applied_inputs, applied_overrides, applied_runtime, elapsed_seconds). The instrument matters: pass `symbol` (a Binance symbol) or `syminfo` (your own qty_step, mintick, ...); a CSV from fetch_binance_ohlcv carries its instrument and needs neither. The lot size is TradingView's own reading for the symbol, from a measured table shipped with this server (Binance's LOT_SIZE.stepSize only for a symbol TradingView does not list; TradingView's usual 0.001 for a listing newer than the table); the tick size and currencies come from Binance's public exchangeInfo (or from the sidecar next to a CSV fetched by fetch_binance_ohlcv). `syminfo` goes over all of it. What was applied is in applied_runtime.syminfo; when the lot grid is unknown, or its lot size is not a TradingView reading, the result has a `warnings` entry. If the report is too large to return inline it is written to report_path and a compact summary (with that path) is returned instead. Use backtest_pine_grid for sweeps.
- `backtest_pine_grid`: Use when the user wants to optimize, sweep, tune, or compare PineScript parameter values (e.g. 'try fast length 8/12/19', 'find the best commission/qty settings') rather than test a single configuration — for one fixed configuration use backtest_pine. Run a parameter sweep: transpile the Pine source ONCE (in-process, no host Docker), then compile (g++) and backtest that C++ against the OHLCV CSV once per combination in the cartesian product of `inputs` × `overrides` grids. Returns a ranked list of {inputs, overrides, summary, elapsed_seconds} entries sorted by `sort_by` descending, plus the top entry under `best`. Cap: max_combinations (default 64). Takes the same `symbol` / `market` / `syminfo` as backtest_pine and applies the instrument to every combination (the result's `instrument` shows it). The lot size is TradingView's own reading for the symbol, from a measured table shipped with this server (Binance's LOT_SIZE.stepSize only for a symbol TradingView does not list; TradingView's usual 0.001 for a listing newer than the table); the tick size and currencies come from Binance's public exchangeInfo (or from the sidecar next to a CSV fetched by fetch_binance_ohlcv). `syminfo` goes over all of it. Set concurrency > 1 to run backtests in parallel — 2-4 is usually plenty.
- `check_tradingview_parity`: Check how closely PineForge reproduces a TradingView backtest, trade by trade. Give the Pine v6 script and TradingView's own Strategy Tester export: the "List of trades" CSV, or the XLSX report as base64. PineForge runs the script on the same market and window and grades the two trade lists with the grader behind its recorded parity figures (pineforge-engine v1.2.0 scripts/verify_corpus.py, byte-identical in v1.3.0 and the frozen 1.4.0 candidate). The execution harness run_strategy.py is copied byte-for-byte from frozen engine candidate b3192bfc2f5a24bf4efd6d1d01e01e8fe619dfed; file identity is not a new native corpus parity result. Returns the tier (excellent, strong, moderate, weak, minimal), each check with its value and thresholds, matched and unmatched trade counts, the first mismatches side by side with hints, and a timezone check. Bars: pass ohlcv_csv or ohlcv_csv_path for any market; without them, BINANCE:<SYMBOL> (spot) and BINANCE:<SYMBOL>.P (USDT-M perpetual) bars are fetched from Binance's public API (at most 100,000 bars); any other symbol needs your bars. No quota and no history window beyond that. Scripts declaring use_bar_magnifier=true also fetch 1-minute bars through the last chart bar's close, counted in that limit, on charts the harness magnifies (coarser than 1 minute, at most 1 day) unless runtime.bar_magnifier is false. With your own bars, optionally pass magnifier_ohlcv_csv or magnifier_ohlcv_csv_path; a script that declares the magnifier but runs without one gets a warning that fills inside bars may differ from TradingView's. Settings the XLSX Properties sheet states are used; an explicit input that disagrees with one is an error. The run applies the instrument's lot size and tick size as backtest_pine does, for BINANCE:<SYMBOL> and BINANCE:<SYMBOL>.P. The lot size is TradingView's own reading for the symbol, from a measured table shipped with this server (Binance's LOT_SIZE.stepSize only for a symbol TradingView does not list; TradingView's usual 0.001 for a listing newer than the table); the tick size and currencies come from Binance's public exchangeInfo (or from the sidecar next to a CSV fetched by fetch_binance_ohlcv). `syminfo` gives your own values and goes over all of it. The result's `applied_instrument` shows what was applied, and `warnings` says when no lot size could be found or its lot size is not a TradingView reading. The run and the grading happen in this image. (read-only)
- `fetch_binance_ohlcv`: Fetch OHLCV candles from Binance public API and write a backtest-ready CSV (header: timestamp,open,high,low,close,volume; timestamp = open time in UNIX ms UTC). Supports `spot` and `usdt_perp` (USDT-margined perpetual futures). Requests larger than 1000 bars are paginated automatically. Also records the symbol's instrument in <output_path>.instrument.json (lot size: TradingView's own reading from a measured table shipped with this server, Binance's LOT_SIZE.stepSize for a symbol TradingView does not list, TradingView's usual 0.001 for a listing newer than the table; tick size and currencies from Binance's public exchangeInfo), which backtest_pine and backtest_pine_grid pick up; the result's `instrument` shows what was recorded. The output path must live inside the MCP cwd unless PINEFORGE_ALLOW_ANYWHERE=1.
- `binance_symbols`: List/validate symbols available on the Binance public API for OHLCV fetching. Filters: `query` (substring of the symbol), `quote_asset` (e.g. 'USDT'), `base_asset` (e.g. 'BTC'), `status` (e.g. 'TRADING'), `contract_type` (futures only, e.g. 'PERPETUAL'). Results are cached 5 min in process. Free. (read-only)
- `list_engine_params`: Returns the full catalog of engine knobs accepted by backtest_pine / backtest_pine_grid in two groups: strategy_overrides (the 9 strategy(...) header fields the runtime reads via PINEFORGE_OVERRIDES — initial_capital, pyramiding, slippage, commission_value, commission_type, default_qty_value, default_qty_type, process_orders_on_close, close_entries_rule) and runtime_args (input_tf, script_tf, bar_magnifier, magnifier_samples, magnifier_dist — args to run_backtest_full, NOT part of the strategy() header). Each entry is {key, type, enum?, description}. Does not run the engine. Use this to discover what knobs the engine exposes before issuing a backtest. (read-only)
- `list_coverage_topics`: START HERE before writing, porting, or backtesting a Pine v6 strategy on PineForge. PineForge implements a SUBSET of Pine v6, so checking coverage first avoids a strategy that compiles but silently misbehaves vs TradingView. Lists every coverage topic with a one-line status (supported / partial / unsupported / via_transpiler) and summary, plus the legend (note: via_transpiler still works end-to-end; unsupported means refused, not compiling, stopping the run where its value is read, or accepted with no effect) and the coverage version. Statuses describe what a backtest on THIS server can do. Cheap, free, local — no engine run, no I/O. Then drill in with get_coverage_topic for one area's per-feature lists, or check_pine_feature to look up a single identifier. (read-only)
- `get_coverage_topic`: Returns the full detail plus the exact supported[], partial[], via_transpiler[] and unsupported[] feature lists for ONE coverage topic id (ids from list_coverage_topics, e.g. 'ta', 'strategy_orders', 'request_security', 'drawing_plotting_alerts'). Use when you are about to work in a feature area and need to know precisely which functions there are implemented vs skipped — e.g. before using request.security, the ta.* library, or strategy risk knobs. Unknown ids return an error marker listing the valid ids. Local, free, no engine run. (read-only)
- `check_pine_feature`: Answer "does PineForge support X?" for a specific Pine v6 identifier or namespace (e.g. 'ta.supertrend', 'alert', 'array.new', 'request.financial'). Use it (a) BEFORE relying on any function you are unsure about while writing a strategy, and (b) to DIAGNOSE a backtest that compiled but behaved wrong or empty — plots, tables and alerts (plot, bgcolor, table, alert) are accepted and produce NO effect, while line, box and label objects are data the strategy can read back. Resolves by exact feature match, then longest namespace prefix, then alias, returning {query, status, topic, note} where status is supported / partial / unsupported / via_transpiler / not_found (via_transpiler = works end-to-end; unsupported = refused, not compiling, stopping the run, or no effect) and the note quotes the catalog entry, which says what THIS server can and cannot do (e.g. request.security on another symbol). Local, free, no engine run. (read-only)
- `engine_info`: Report the bundled backtest engine: mode, baked-in flag, and version. This image runs the engine in-process (no host Docker daemon needed). (read-only)

## FAQ

### Does this require an API key?

No, the server does not require an API key for operation.

### Can I use my own historical data?

Yes, you can run backtests against your own OHLCV CSV files by mounting them to the container.

### How accurate are the backtests compared to TradingView?

The engine is designed for deterministic parity with TradingView, with recent benchmarks showing 99.92% excellent results in graded probes.

### What are the system requirements?

You need Docker installed and outbound network access if you intend to use the Binance fetching tools.
