IB Analytics

Interactive Brokers portfolio analytics library with multi-account support.

Features

• 📊 Multi-Account Support: Analyze multiple IB accounts simultaneously

• 🔄 Flex Query API Integration: Automated data fetching via IB Flex Query API v3

• 📈 Comprehensive Analysis: Performance, tax, cost, risk, and bond analytics

• 🎯 Type-Safe: Built with Pydantic v2 for robust data validation

• ⚡ Async Support: Parallel data fetching for multiple accounts

• 📄 Rich Reports: Console, HTML, and optional PDF reporting

Installation

Quick Start

1. Configuration

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

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

3. Run Analysis

4. Generate Reports

Docker Usage

Quick Start with Docker

Docker Compose

Create .env file:

Run:

Docker Security Features

• Non-root user: Runs as mcpuser (UID 1000)

• Read-only filesystem: Root filesystem is read-only

• Resource limits: CPU (2 cores) and memory (2GB) limits

• No new privileges: Prevents privilege escalation

• Data persistence: Data stored in mounted volume

Programmatic Usage

Project Structure

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)

IB Analytics provides advanced investment analysis tools through the MCP server. These tools integrate Yahoo Finance data for comprehensive market analysis.

Stock & Fund Analysis

get_stock_info - Comprehensive Stock Information

Get detailed information about stocks, ETFs, and funds including fundamental metrics.

Features:

• Real-time price data (current, open, high, low, volume)

• Valuation metrics (P/E, P/B, P/S, PEG, EV/EBITDA, EV/Revenue)

• Profitability metrics (profit margin, ROE, ROA, operating margin, EPS)

• Financial health (total cash, debt, debt-to-equity, current/quick ratios, FCF)

• Growth metrics (revenue growth, earnings growth)

• Dividend information (yield, ex-date, payment date)

• Trading information (52-week high/low, market cap, volume)

Example Usage:

get_current_price - Quick Price Check

Get current price and key metrics for quick market checks.

Example Usage:

get_stock_data - Historical Price Data with Technical Indicators

Fetch OHLCV data with optional technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands).

Example Usage:

Comparative Analysis

compare_with_benchmark - Performance vs Benchmark

Compare stock/fund performance against a benchmark (default: SPY).

Features:

• Return comparison (total return, annualized return)

• Volatility analysis (standard deviation comparison)

• Risk metrics (beta, alpha, correlation)

• Risk-adjusted returns (Sharpe ratio comparison)

• Interpretation and insights

Example Usage:

get_analyst_consensus - Analyst Ratings & Target Prices

Get analyst recommendations, target prices, and earnings estimates.

Features:

• Rating distribution (strong buy/buy/hold/sell/strong sell)

• Consensus rating derived from distribution

• Target prices (mean, median, high, low)

• Upside potential percentage

• Earnings estimates (date, EPS range, revenue estimates)

Example Usage:

Portfolio-Level Analysis

calculate_portfolio_metrics - Advanced Portfolio Metrics

Calculate comprehensive risk-adjusted performance metrics for your portfolio.

Features:

• Return metrics: Total return, annualized return, volatility

• Risk-adjusted ratios:

  • Sharpe Ratio: Risk-adjusted return (excess return / total risk)

  • Sortino Ratio: Downside risk-adjusted return

  • Calmar Ratio: Return / maximum drawdown

  • Treynor Ratio: Excess return / systematic risk (beta)

  • Information Ratio: Excess return / tracking error

• Risk metrics:

  • Maximum drawdown (largest peak-to-trough decline)

  • Downside deviation (volatility of negative returns)

  • Beta (systematic risk vs benchmark)

  • Tracking error (deviation from benchmark)

  • Alpha (excess return vs expected return)

Parameters:

• csv_path: Path to IB Flex Query CSV file

• benchmark: Benchmark symbol (default: "SPY")

• risk_free_rate: Annual risk-free rate (default: 0.05 = 5%)

• period: Time period for analysis (1mo, 3mo, 6mo, 1y, 2y, 5y)

Example Usage:

Limitations:

• ⚠️ Requires Yahoo Finance data for portfolio positions

• ⚠️ Will not work for bond-only portfolios (STRIPS bonds have no Yahoo Finance data)

• ✅ Works well for stock and ETF portfolios

analyze_portfolio_correlation - Diversification Analysis

Analyze correlation between portfolio positions to assess diversification.

Features:

• Correlation matrix between all positions

• High correlation pairs identification (|r| > 0.7)

• Portfolio beta vs benchmark (default: SPY)

• Diversification score (0-100)

• Position weights in portfolio

• Interpretation and recommendations

Parameters:

• csv_path: Path to IB Flex Query CSV file

• period: Time period for correlation analysis (1mo, 3mo, 6mo, 1y, 2y, 5y)

Example Usage:

Limitations:

• ⚠️ Requires Yahoo Finance data for portfolio positions

• ⚠️ Will not work for bond-only portfolios

• ✅ Best for analyzing stock/ETF portfolio diversification

Options Analysis

get_options_chain - Options Data

Get calls and puts data for a stock including strike prices, volume, open interest, and implied volatility.

calculate_put_call_ratio - Market Sentiment

Calculate put/call ratio based on open interest or volume to gauge market sentiment.

Example Usage:

News & Market Intelligence

get_stock_news - Latest News Articles

Get the latest news articles for any stock symbol from Yahoo Finance.

Features:

• Latest news articles (up to 50)

• Article metadata (title, publisher, publish time, summary)

• Direct links to full articles

• Thumbnail images for visual context

• Related ticker symbols

• Multiple content types (stories, videos, press releases)

Parameters:

• symbol: Stock ticker symbol (e.g., "AAPL", "TSLA", "QQQ")

• limit: Number of articles to return (default: 10, max: 50)

Example Usage:

Response Includes:

• Title: Article headline

• Publisher: News source (e.g., Yahoo Finance, Bloomberg, Reuters)

• Link: Direct URL to full article

• Publish Time: When the article was published (ISO 8601 format)

• Summary: Brief article summary or description

• Type: Content type (STORY, VIDEO, etc.)

• Thumbnail: Image URL for articles with visuals

• Related Tickers: Other stocks mentioned in the article

Use Cases:

• Investment Research: Stay updated on company news and developments

• Market Sentiment: Gauge market sentiment from news coverage

• Due Diligence: Research companies before making investment decisions

• Portfolio Monitoring: Track news for holdings in your portfolio

• Event-Driven Trading: Identify market-moving events quickly

Example Natural Language Queries:

Usage Examples in Claude Desktop

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

Technical Notes

Data Sources:

• Portfolio data: Interactive Brokers Flex Query (CSV/XML)

• Market data: Yahoo Finance via yfinance library

• Real-time quotes: Yahoo Finance delayed quotes (15-20 minutes)

Performance Metrics Definitions:

• Sharpe Ratio: (Return - Risk-free rate) / Volatility. Higher is better. >1 is good, >2 is excellent.

• Sortino Ratio: Like Sharpe but only penalizes downside volatility. Better for asymmetric returns.

• Calmar Ratio: Annualized return / Maximum drawdown. Measures return per unit of downside risk.

• Treynor Ratio: (Return - Risk-free rate) / Beta. Measures return per unit of systematic risk.

• Information Ratio: (Portfolio return - Benchmark return) / Tracking error. Measures active management skill.

• Beta: Systematic risk relative to benchmark. 1.0 = same risk as benchmark, >1.0 = more volatile.

• Alpha: Excess return vs expected return (CAPM). Positive alpha = outperformance after risk adjustment.

• Maximum Drawdown: Largest peak-to-trough decline. Key risk metric for understanding worst-case scenarios.

Correlation Interpretation:

• |r| > 0.7: High correlation (limited diversification benefit)

• 0.3 < |r| < 0.7: Moderate correlation (some diversification)

• |r| < 0.3: Low correlation (good diversification)

• Negative correlation: Positions move in opposite directions (excellent diversification)

Usage Modes

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

1. Claude Desktop (Conversational Analysis)

Target Users: Investors, portfolio managers, financial analysts

Use Case: Natural language portfolio analysis and investment research

Setup: Install MCP server in Claude Desktop configuration

Capabilities:

• Natural language queries ("What's my portfolio performance this quarter?")

• Automated data fetching from IB Flex Query API

• Comprehensive portfolio analysis with one question

• Investment research (stock info, news, analyst ratings)

• Risk assessment and tax planning recommendations

Example Workflow:

2. Claude Code + MCP (Custom Analysis)

Target Users: Data scientists, quantitative analysts, developers

Use Case: Flexible data analysis with composable MCP tools

Setup: Use Claude Code with MCP server enabled

Capabilities:

• Compose multiple MCP tools for custom analysis

• Fine-grained data access (get_trades, get_positions, calculate_metric)

• Period-over-period comparisons

• Custom metric calculations

• Strategy resources (tax context, rebalancing context, risk context)

Example Workflow:

3. Claude Code + Repository (Advanced Development)

Target Users: Developers, power users, automation engineers

Use Case: Complete development workflow automation with specialized sub-agents

Setup: Clone repository and use Claude Code in project directory

Capabilities:

• 7 Specialized Sub-Agents:

  • data-analyzer: Financial data analysis specialist

  • test-runner: Testing and quality assurance

  • code-implementer: Feature implementation with TDD

  • code-reviewer: Code quality enforcement

  • performance-optimizer: Profiling and optimization

  • api-debugger: IB API troubleshooting

  • issue-analyzer: GitHub issue analysis

• 12 Slash Commands: Automated workflows (see .claude/README.md)

• GitHub Integration: Issue → Branch → Tests → Code → PR workflow

• Quality Gates: Automated black, ruff, mypy, pytest execution

• TDD Workflow: Test-first development enforced

Example Workflow:

Additional Commands:

See .claude/README.md for complete sub-agent and slash command documentation.

MCP Server Integration

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

Quick Start

Features

• 16 Tools:

  • IB Portfolio: Fetch data, performance/cost/bond/tax/risk analysis, portfolio summary

  • Stock Analysis: Stock info, current price, historical data, options chain, put/call ratio, news

  • Investment Analysis: Benchmark comparison, portfolio metrics, correlation analysis, analyst consensus

• 6 Resources: Access portfolio data, account info, trades, and positions via URI patterns

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

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

See .claude/CLAUDE.md for detailed MCP documentation and usage patterns.

Development

Requirements

• Python 3.9+

• 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

The IB Analytics MCP server implements security best practices:

• 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

Enable debug mode for detailed error information (development only):

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

• Use separate credentials for development and production

• Regularly rotate API tokens

Troubleshooting

Common Issues

1. "Configuration error: Failed to load credentials"

Problem: QUERY_ID or TOKEN not found in environment

Solution:

2. "Validation error for 'start_date': Invalid date format"

Problem: Date format is incorrect

Solution: Use YYYY-MM-DD format

3. "IB API error: Statement not yet ready"

Problem: IB Flex Query is still processing

Solution: The server automatically retries (up to 3 times). If it still fails, wait a few minutes and try again.

4. "Yahoo Finance API error: No data found for SYMBOL"

Problem: Invalid stock symbol or no data available

Solution:

• Verify the ticker symbol is correct

• Check if the symbol is traded on supported exchanges

• Try a different period or interval

5. "Timeout: IB API call timed out after 60 seconds"

Problem: API call took too long

Solution:

• Check your internet connection

• Reduce the date range

• Try again during off-peak hours

Testing

Run tests to verify your installation:

MCP Server Testing

Test the MCP server connection:

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

4. Parallel processing: Use async operations where possible

License

MIT

Author

Kenichiro Nishioka

Support

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