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 - .envfiles 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:
- Reduce date ranges: Fetch smaller time periods 
- Use file caching: Reuse previously fetched data 
- Limit technical indicators: Only request needed indicators 
- Parallel processing: Use async operations where possible 
License
MIT
Author
Kenichiro Nishioka
Support
For issues and questions, please check the IB Flex Query documentation.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables comprehensive analysis of Interactive Brokers portfolios through automated data fetching and multi-dimensional analytics. Provides performance, tax, cost, risk, and bond analysis across multiple accounts with rich reporting capabilities.