IB Analytics

Interactive Brokers portfolio analytics library with AI-powered investment analysis and development automation.

Overview

IB Analytics enables systematic analysis of trading performance across multiple IB accounts with type-safe, modular, and extensible architecture.

For Investors (Modes 1 & 2):

• 95% faster investment strategy generation (6-8 hours → 15-20 minutes)

• Parallel market analysis of all holdings simultaneously

• Consolidated multi-account view with accurate portfolio metrics

• Professional options strategies with specific strikes, Greeks, and Max Pain

• Tax-optimized execution plans across multiple accounts

• Multi-timeframe technical analysis with entry/exit signals

For Developers (Mode 3):

• 90% faster issue resolution (80 minutes → 8 minutes via /resolve-gh-issue)

• Automated quality gates (black, ruff, mypy, pytest)

• Complete TDD workflow (tests → code → PR automation)

• 11 specialized AI agents + 20 slash commands

Installation

# Install with pip
pip install -e .

# Install with MCP server support
pip install -e ".[mcp]"

# Install with development dependencies
pip install -e ".[dev]"

# Install all optional dependencies
pip install -e ".[dev,mcp,visualization,reporting]"

Quick Start

1. Configuration

Create a .env file with your IB Flex Query credentials:

QUERY_ID=your_query_id
TOKEN=your_token_here

Note: To analyze multiple accounts, configure them in your IB Flex Query settings. A single query can return data for multiple accounts.

2. Fetch Data

# Fetch data
ib-sec-fetch --start-date 2025-01-01 --end-date 2025-10-05

# Split by account (if query contains multiple accounts)
ib-sec-fetch --split-accounts --start-date 2025-01-01 --end-date 2025-10-05

3. Run Analysis

# Run comprehensive analysis
ib-sec-analyze --account U1234567

# Run specific analyzer
ib-sec-analyze --account U1234567 --analyzer performance

# Analyze all accounts
ib-sec-analyze --all-accounts

4. Generate Reports

# Console report
ib-sec-report --account U1234567 --format console

# HTML report with charts
ib-sec-report --account U1234567 --format html --output report.html

Docker Usage

Run IB Analytics in an isolated container with security hardening (non-root user, read-only filesystem, resource limits).

docker-compose up  # or: docker build -t ib-sec-mcp . && docker run -e QUERY_ID=... -e TOKEN=... ib-sec-mcp

See docs/docker.md for full setup, docker-compose configuration, and troubleshooting.

Programmatic Usage

from ib_sec_mcp import FlexQueryClient, Portfolio
from ib_sec_mcp.analyzers import PerformanceAnalyzer, TaxAnalyzer
from datetime import date

# Initialize client
client = FlexQueryClient(query_id="your_query_id", token="your_token_here")

# Fetch data
data = client.fetch_statement(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 10, 5)
)

# Create portfolio
portfolio = Portfolio.from_flex_data(data)

# Run analysis
perf_analyzer = PerformanceAnalyzer(portfolio)
results = perf_analyzer.analyze()

# Generate report
from ib_sec_mcp.reports import ConsoleReport
report = ConsoleReport(results)
report.render()

Project Structure

ib-sec/
├── ib_sec_mcp/           # Main library
│   ├── api/               # Flex Query API client
│   ├── core/              # Core business logic
│   ├── models/            # Pydantic data models
│   ├── analyzers/         # Analysis modules
│   ├── reports/           # Report generators
│   └── utils/             # Utilities
├── tests/                 # Test suite
└── data/                  # Data directory
    ├── raw/              # Raw CSV/XML data
    └── processed/        # Processed data

Architecture

Layer Structure

┌─────────────────────────────────────┐
│      CLI Layer (typer + rich)       │
├─────────────────────────────────────┤
│    Reports Layer (console/html)     │
├─────────────────────────────────────┤
│   Analyzers Layer (5 analyzers)     │
├─────────────────────────────────────┤
│  Core Logic (parser/calc/agg)       │
├─────────────────────────────────────┤
│   Models Layer (Pydantic v2)        │
├─────────────────────────────────────┤
│    API Layer (sync + async)         │
└─────────────────────────────────────┘

Design Patterns

Template Method (BaseAnalyzer):

class BaseAnalyzer(ABC):
    @abstractmethod
    def analyze(self) -> AnalysisResult:
        pass

    def _create_result(self, **kwargs) -> AnalysisResult:
        """Shared result creation with metadata"""
        result = AnalysisResult(self.analyzer_name, **kwargs)
        result["timestamp"] = datetime.now().isoformat()
        return result

class PerformanceAnalyzer(BaseAnalyzer):
    def analyze(self) -> AnalysisResult:
        trades = self.get_trades()
        # ... compute metrics ...
        return self._create_result(win_rate=win_rate, profit_factor=pf)

Strategy (Reports):

class BaseReport(ABC):
    @abstractmethod
    def render(self) -> str:
        pass

Factory Method (Parsers, Portfolio):

account = CSVParser.to_account(csv_data, from_date, to_date)
portfolio = Portfolio.from_accounts(accounts, base_currency="USD")

See docs/architecture.md for data flow diagrams, layer responsibilities, and new feature decision guide.

Available Analyzers

• PerformanceAnalyzer: Overall trading performance metrics

• TaxAnalyzer: Tax liability calculations (OID, capital gains)

• CostAnalyzer: Commission and cost efficiency analysis

• RiskAnalyzer: Interest rate and market risk scenarios

• BondAnalyzer: Bond-specific analytics (YTM, duration, etc.)

Investment Analysis Tools (MCP)

45 MCP tools for stock, options, and portfolio analysis via Yahoo Finance and IB portfolio data.

Full reference (all arguments, return values, examples): docs/mcp-tools-reference.md

Usage Examples in Claude Desktop

Once you've set up the MCP server in Claude Desktop, you can use natural language:

"Show me detailed information for AAPL including all fundamental metrics"

"Compare my portfolio performance against the S&P 500 over the last year"

"What's the correlation between positions in my portfolio? Are they well diversified?"

"Analyze market sentiment for NVDA - should I buy now or wait?"

"What's the composite sentiment for SPY across news, options, and technicals?"

"Create a comprehensive investment plan for my portfolio"

Usage Modes

IB Analytics supports three distinct usage modes optimized for different user types:

Mode 3 example:

/resolve-gh-issue 42
# Automated: Issue analysis → Tests → Implementation → Quality checks → PR
# Result: 80 minutes → 8 minutes (90% time savings)

Detailed architecture, workflow examples, and implementation guide: CLAUDE.md

See .claude/README.md for all 11 sub-agents and 20 slash commands.

Feature Comparison

Recommendation:

• Start with Mode 1 if you're an investor looking for quick insights

• Use Mode 2 if you need custom analysis or programmatic access

• Adopt Mode 3 if you're developing features or need advanced automation

Position History & Time-Series Analysis

IB Analytics automatically stores daily position snapshots in SQLite (data/processed/positions.db) for historical analysis and time-series tracking.

Features: Automatic sync on data fetch, multi-account support, 5 MCP tools for querying history.

Full schema, indexes, and migration procedures: docs/database-schema.md

MCP Server Integration

IB Analytics provides a Model Context Protocol (MCP) server for integration with Claude Desktop and Claude Code.

Features

• 45 Tools: Portfolio analysis, market data, risk/tax/cost analytics, rebalancing, dividend/sector/FX analysis

• 9 Resources: Portfolio data, account info, trades, positions, and strategy context via URI patterns

• 5 Prompts: Pre-configured analysis templates for common workflows

Setup Options

Option 1: Git リポジトリから直接実行（推奨・クローン不要）

インストール不要。設定ファイルに追記するだけで使用できます。

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ib-sec-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "ib-sec-mcp[mcp] @ git+https://github.com/knishioka/ib-sec-mcp",
        "ib-sec-mcp"
      ],
      "env": {
        "QUERY_ID": "your_query_id",
        "TOKEN": "your_token"
      }
    }
  }
}

Claude Code (プロジェクトの .mcp.json):

{
  "mcpServers": {
    "ib-sec-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "ib-sec-mcp[mcp] @ git+https://github.com/knishioka/ib-sec-mcp",
        "ib-sec-mcp"
      ],
      "env": {
        "QUERY_ID": "${QUERY_ID}",
        "TOKEN": "${TOKEN}"
      }
    }
  }
}

Note: [mcp] extra の指定が必須です（fastmcp, scipy, pyyaml が含まれます）。

キャッシュ: 初回のみ依存関係をダウンロード（~/.cache/uv）。2回目以降は即座に起動します。最新版を取得したい場合は uvx --refresh オプションを使用してください。

Option 2: ローカルリポジトリから実行（開発者向け）

リポジトリをクローンして開発する場合：

git clone https://github.com/knishioka/ib-sec-mcp.git
cd ib-sec-mcp
cp .mcp.json.example .mcp.json  # パスを編集

.mcp.json:

{
  "mcpServers": {
    "ib-sec-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/ib-sec-mcp", "run", "ib-sec-mcp"],
      "env": {
        "QUERY_ID": "${QUERY_ID}",
        "TOKEN": "${TOKEN}"
      }
    }
  }
}

Prerequisites

• uv インストール済み: brew install uv または curl -LsSf https://astral.sh/uv/install.sh | sh

• IB Flex Query の QUERY_ID と TOKEN（IB ポータルで取得）

See MCP Tools Reference for complete documentation of all 45 tools, 9 resources, and 5 prompts.

See .claude/CLAUDE.md for development guide and usage patterns.

Documentation

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=ib_sec_mcp --cov-report=html

# Code formatting with Ruff
ruff format ib_sec_mcp tests

# Linting with Ruff
ruff check --fix ib_sec_mcp tests

# Type checking with mypy
mypy ib_sec_mcp

# Run all pre-commit hooks manually
pre-commit run --all-files

Requirements

• Python 3.12+

• Interactive Brokers account with Flex Query access

Dependencies

• requests (2.32.5+): HTTP client for API calls

• pandas (2.2.3+): Data analysis and manipulation

• pydantic (2.10.0+): Data validation and settings management

• httpx (0.27.0+): Async HTTP client for parallel requests

• rich (13.7.0+): Beautiful console output

• typer (0.12.0+): CLI framework

• yfinance (0.2.40+): Yahoo Finance data integration

• fastmcp (2.0.0+): Model Context Protocol server framework

Security

MCP Server Security

• Error Masking: Internal error details are masked from clients (configurable with IB_DEBUG=1)

• Input Validation: All inputs are validated before processing

• File Path Protection: Path traversal attacks are prevented

• File Size Limits: Maximum file size: 10MB

• Timeout Protection: All operations have timeout limits

• Retry Logic: Automatic retry for transient errors (max 3 attempts)

Debug Mode

export IB_DEBUG=1
ib-sec-mcp

Warning: Never enable debug mode in production as it exposes internal error details.

Credentials Security

• Never commit .env files to version control

• Store credentials in environment variables or secure secret management systems

• Regularly rotate API tokens

Command Selection Guide

For an interactive decision flowchart and full command reference table, see .claude/README.md.

Quick reference:

• Investors: /investment-strategy → /analyze-symbol SYMBOL → /options-strategy SYMBOL

• Developers: /resolve-gh-issue N → /quality-check → /test

Troubleshooting

For a comprehensive troubleshooting guide with detailed error cases, prevention tips, and the full exception hierarchy, see docs/troubleshooting.md.

Testing

pip install -e ".[dev]"
pytest
pytest --cov=ib_sec_mcp --cov-report=html

MCP Server Testing

# Start server in debug mode
IB_DEBUG=1 ib-sec-mcp

Performance Optimization

If experiencing slow performance:

1. Reduce date ranges: Fetch smaller time periods

2. Use file caching: Reuse previously fetched data

3. Limit technical indicators: Only request needed indicators

License

MIT

Author

Kenichiro Nishioka

Support

For issues and questions, please check the IB Flex Query documentation.