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