TradeBlocks

Options trading analytics platform with a web dashboard and AI-powered analysis via MCP (Model Context Protocol).

Web App | npm | Docker Hub | Buy Me a Coffee

Repository Structure

tradeblocks/
├── app/                      # Next.js web application
├── components/               # React components (shadcn/ui + Plotly charts)
├── tests/                    # Jest test suites
├── docs/                     # Documentation
│   └── development.md        # Architecture and local dev guide
└── packages/
    ├── lib/                  # Core business logic (@tradeblocks/lib)
    └── mcp-server/           # MCP server (npm: tradeblocks-mcp)

Quick Start

Development Setup

git clone https://github.com/tradeblocks-org/tradeblocks.git
cd tradeblocks
npm install
npm run dev              # Web dashboard at http://localhost:3000

MCP Server

# Run directly with npx
npx tradeblocks-mcp ~/Trading/backtests

# Or from source
npm run build -w packages/mcp-server
node packages/mcp-server/server/cli.js ~/Trading/backtests

Testing

npm test                 # All tests
npm test -- path/to/file.test.ts    # Single file
npm run test:coverage    # Coverage report

Documentation

Guide	Description
Getting Started	Installation, env vars, first import
Market Data	Imports, enrichment, computed-Greeks recipe
MCP Tools	Complete tool reference by category
Architecture	Data flow, schemas, key patterns
Development Guide	Contributing, local dev setup
MCP Server	Installation, platform configuration
Usage Guide	Tool reference, example workflows
Agent Skills	Guided conversational analysis

Data Format

Both the web dashboard and MCP server accept CSV exports from platforms like Option Omega. Each block contains:

• tradelog.csv (required) - Trade history with P/L, dates, strategy name
• dailylog.csv (optional) - Daily portfolio values for enhanced drawdown calculations
• reportinglog.csv (optional) - Actual/reported trades for backtest vs live comparison

Files are auto-detected by column headers, not filenames. See Usage Guide for format details.

Option Omega

TradeBlocks never calls Option Omega. Install both MCP servers, TradeBlocks and OO's, in the same AI client:

• Capture (Claude Code only). The optional tradeblocks-skills plugin's /tradeblocks:oo-capture saves OO's responses for a saved backtest, saved portfolio or run to disk, verifies the trades against OO's own count and net profit, and imports the trade log into one block with OO's marked daily curve. A run whose OO headline reports no date range is imported with its trades only, and the capture says so. It needs TradeBlocks running locally over stdio; it is not supported with the Docker image or HTTP mode.
• CSV fallback (every client and mode). Export the trade log, and optionally the daily log, from OO and import both with one import_csv call using dailyLogPath. For Docker/HTTP, put the CSVs inside the server's mounted data directory.
• Prompts. bring-in-oo-backtest, is-this-optimum-real, stress-oo-portfolio, live-vs-oo and allocate-oo-portfolio guide the OO workflows. See the MCP server README.

Capture is verified against OO's staging MCP server. See the 4.0.0 release notes.

Features Overview

Web Dashboard

• Performance dashboards with equity curves, drawdowns, monthly returns
• Risk tooling: Monte Carlo simulator, position sizing, correlation analysis
• Block-based organization for multiple strategies
• Client-side storage (IndexedDB) - data stays on your machine

MCP Server

• Tools for statistics, simulations, walk-forward analysis, and SQL queries
• SQL analytics layer (run_sql + describe_database) for flexible data exploration
• Massive.com API integration for automated market data import
• Market data import and enrichment (import_market_csv + enrich_market_data)
• Trade replay with MFE/MAE analysis using historical option minute bars
• Lookahead-free trade enrichment with market context (VIX regimes, intraday timing)
• Works with Claude Desktop, Claude Code, Codex CLI, Gemini CLI, ChatGPT, Google AI Studio
• Agent skills for guided strategy health checks and portfolio recommendations

Contributing

1. Create a feature branch
2. Update or add tests when behavior changes
3. Run npm run lint and npm test before opening a pull request

License

MIT