Investment Statement MCP Server

Parse and query investment statements from multiple institutions using natural language.

Features

• Multi-Institution Support: Questrade, Interactive Brokers, Scotia iTRADE, TD Direct Investing

• Hybrid Storage: SQLite for structured queries + LanceDB for semantic search

• Natural Language Queries: Ask questions like "What were my dividends in Q3?" or "Show my SPY holdings"

• Structured Tools: Programmatic access via MCP tools

• Portfolio Analytics: Risk metrics, performance tracking, benchmark comparisons

• Monte Carlo Simulation: 5-year portfolio projections with percentile analysis and visualizations

• Archive Management: Keeps original PDFs/CSVs and parsed JSON for reference

Installation

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

Configuration

The server is configured via .mcp.json. Key environment variables:

• LANCEDB_PATH: Vector database location (default: ./data/lancedb)

• SQLITE_PATH: SQLite database location (default: ./data/statements.db)

• PDF_ARCHIVE_PATH: Original PDF storage (default: ./data/pdfs)

• JSON_ARCHIVE_PATH: Parsed JSON storage (default: ./data/json)

• MODEL_NAME: Embedding model (default: all-MiniLM-L6-v2)

Usage

Starting the Server

python -m src.server

Indexing Statements

# Via MCP tool
index_statement("/path/to/statement.pdf")

Querying Data

Natural Language Search:

search_statements("What were my total dividends in 2025?", limit=10)

Structured Queries:

get_holdings_by_symbol("SPY")
get_transactions_by_date("2025-01-01", "2025-09-30")
get_account_balance("51516162", "2025-09-30")

Monte Carlo Simulation:

# Run portfolio projection simulation
result = run_monte_carlo_simulation(
    n_simulations=10000,      # 10,000 simulation paths
    projection_years=5,        # Project 5 years into the future
    account_numbers=None,      # None = all accounts
    percentiles=[10, 25, 50, 75, 90]
)

# Results saved to:
# - Timestamped: data/reports/monte_carlo/2025-11-26_153034/
# - Latest: data/reports/monte_carlo/latest/
#
# Output includes:
# - 3 PNG charts (fan chart, distribution, confidence intervals)
# - 3 CSV files (projections, summary, historical_returns)

See MONTE_CARLO.md for detailed documentation.

Resources

• statements://catalog - List all indexed statements

• statements://{statement_id} - Get specific statement

• statements://{statement_id}/summary - Account summary

• statements://{statement_id}/holdings - Holdings/positions

• statements://{statement_id}/transactions - Transaction history

Supported Statements

Questrade

• ✅ Account Summary (balances, FX rates, TFSA info)

• ✅ Holdings/Positions (securities with cost basis, P&L)

• ✅ Transactions (trades, dividends, deposits, withdrawals)

Interactive Brokers (Coming Soon)

• ⏳ Planned

Scotia (Coming Soon)

• ⏳ Planned

Development

# Run tests
pytest

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

# Format code
black src tests

# Lint code
ruff check src tests

Architecture

• FastMCP 2.0: MCP server framework

• pymupdf4llm: PDF parsing optimized for LLMs

• LanceDB: Vector database for semantic search

• SQLite: Structured metadata storage

• sentence-transformers: Embedding generation

License

MIT