TradeBlocks MCP Server

Model Context Protocol (MCP) server for options trading analysis. Works with Claude Desktop, Claude Code, Codex CLI, Gemini CLI, ChatGPT, Google AI Studio, and any MCP-compatible client.

Features

- 34 MCP tools for comprehensive trading analysis
- SQL analytics layer - run_sql for arbitrary queries, describe_database for schema discovery
- Two transport modes: stdio (CLI tools) and HTTP (web platforms)
- Block-based data organization - each folder is a trading strategy
- Automatic caching - statistics cached in block.json for fast access
- Flexible CSV detection - auto-detects file types by column headers

Installation

$3

Download the latest .mcpb file from GitHub Releases and double-click to install.

The installer will prompt you to select your Trading Data Directory.

$3

Run directly without installation:

``bash


stdio mode (Claude Desktop, Claude Code, Codex CLI, Gemini CLI)

npx tradeblocks-mcp ~/Trading/backtests

HTTP mode (ChatGPT, Google AI Studio, Julius AI)

npx tradeblocks-mcp --http ~/Trading/backtests
`

See Configuration by Platform below for platform-specific setup.

$3

`bash
git clone https://github.com/davidromeo/tradeblocks
cd tradeblocks
npm install
npm run build -w packages/mcp-server

Run the server


node packages/mcp-server/server/index.js ~/Trading/backtests
`

Quick Start

1. Set up your data - Create folders for each strategy with CSV files
2. Connect your AI platform - See Configuration by Platform below
3. Start analyzing - Ask your AI to "list my backtests" or "run a health check on iron-condor"

For detailed usage examples, see docs/USAGE.md.

Configuration by Platform

$3

| Platform | Config Location |
|----------|-----------------|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |

`json
{
"mcpServers": {
"tradeblocks": {
"command": "npx",
"args": ["tradeblocks-mcp", "/path/to/your/backtests"]
}
}
}
`

$3

`bash


Add the MCP server

claude mcp add tradeblocks -- npx tradeblocks-mcp ~/Trading/backtests

Or with environment variable

export BLOCKS_DIRECTORY=~/Trading/backtests
claude mcp add tradeblocks -- npx tradeblocks-mcp
`

$3

Add to ~/.codex/config.toml:

`toml
[mcp_servers.tradeblocks]
command = "npx"
args = ["tradeblocks-mcp", "/path/to/your/backtests"]
`

Or add via command line:

`bash
codex mcp add tradeblocks -- npx tradeblocks-mcp ~/Trading/backtests
`

See Codex MCP documentation for more options.

$3

Add to ~/.gemini/settings.json:

`json
{
"mcpServers": {
"tradeblocks": {
"command": "npx",
"args": ["tradeblocks-mcp", "/path/to/your/backtests"]
}
}
}
`

See Gemini CLI MCP documentation for more options.

$3

Web AI platforms require HTTP transport with an ngrok tunnel:

Terminal 1: Start HTTP server
`bash
tradeblocks-mcp --http ~/Trading/backtests
`

Terminal 2: Expose via ngrok
`bash
ngrok http 3100
`

Then add the ngrok URL (https://xxx.ngrok.io/mcp) to your platform's MCP settings.

See Web Platforms Guide for detailed setup instructions.

Transport Modes

| Mode | Flag | Use Case | Platforms |
|------|------|----------|-----------|
| stdio | (default) | Local CLI tools | Claude Desktop, Claude Code, Codex CLI, Gemini CLI |
| HTTP | --http | Web platforms via ngrok | ChatGPT, Google AI Studio, Julius AI |

`bash


stdio mode (default)

tradeblocks-mcp ~/backtests

HTTP mode

tradeblocks-mcp --http ~/backtests
tradeblocks-mcp --http --port 8080 ~/backtests
`

Agent Skills

For guided conversational workflows, install the bundled agent skills:

`bash


Install skills to Claude Code

tradeblocks-mcp install-skills

Install to other platforms

tradeblocks-mcp install-skills --platform codex
tradeblocks-mcp install-skills --platform gemini

Check installation status

tradeblocks-mcp check-skills

Remove skills

tradeblocks-mcp uninstall-skills
`

Skills provide structured prompts for tasks like:
- Strategy health checks
- Walk-forward analysis interpretation
- Portfolio addition recommendations
- Correlation analysis

See Agent Skills README for details.

Block Directory Structure

Each folder in your blocks directory represents a trading strategy:

`
backtests/
SPX-Iron-Condor/
tradelog.csv # Required - trade history
dailylog.csv # Optional - daily portfolio values
reportinglog.csv # Optional - live/reported trades
block.json # Auto-generated - cached metadata
NDX-Put-Spread/
my-export.csv # Works! Auto-detected by columns
...
`

$3

tradelog.csv - Trade records with these key columns:
- Date Opened, Time Opened, Date Closed, Time Closed
- P/L (gross profit/loss)
- Strategy, Legs (or Symbol)
- No. of Contracts, Premium (optional)

dailylog.csv - Daily portfolio values:
- Date
- Net Liquidity (or Portfolio Value, Equity)
- P/L, Drawdown % (optional)

Flexible Detection: Files don't need standard names. The server detects CSV types by examining column headers (ISS-006).

Available Tools

$3


| Tool | Description |
|------|-------------|
| list_blocks | List all available blocks with summary stats |
| get_block_info | Detailed info for a specific block |
| get_statistics | Performance metrics (Sharpe, Sortino, drawdown, etc.) |
| get_strategy_comparison | Compare strategies within a block |
| compare_blocks | Compare statistics across multiple blocks |

$3

| Tool | Description |
|------|-------------|
| run_walk_forward | Walk-forward analysis with configurable windows |
| run_monte_carlo | Monte Carlo simulation with worst-case scenarios |
| get_correlation_matrix | Strategy correlation matrix (Kendall, Spearman, Pearson) |
| get_tail_risk | Tail dependence and copula-based risk analysis |
| get_position_sizing | Kelly criterion position sizing |

$3

| Tool | Description |
|------|-------------|
| get_performance_charts | 16 chart types (equity, drawdown, distribution) |
| get_period_returns | Returns aggregated by time period |
| compare_backtest_to_actual | Backtest vs live performance comparison |

$3

| Tool | Description |
|------|-------------|
| run_sql | Execute SQL queries against trades and market data |
| describe_database | Schema discovery with table info and example queries |

$3

| Tool | Description |
|------|-------------|
| import_csv | Import a CSV file as a new block (CLI only - not available in Claude Desktop) |

Development

`bash


Watch mode

npm run dev

Build

npm run build

Run tests

npm test

Pack MCPB bundle

npm run mcpb:pack
``

Market Data (Optional)

For market context (VIX regimes, intraday timing, gap analysis), export SPX/VIX data from TradingView using the included PineScript indicators. The MCP server syncs these CSVs into DuckDB automatically.

See scripts/README.md for setup instructions, field documentation, and the 3 PineScript indicators.

Related

- Usage Guide - Detailed usage examples and workflows
- Web Platforms Guide - Connect to ChatGPT, Google AI Studio, Julius
- Agent Skills - Conversational workflows for guided analysis
- Market Data Scripts - TradingView PineScript indicators for SPX/VIX data
- Main Application - Web-based UI for TradeBlocks