README.md•2.61 kB
# Investment Statement MCP Server
Parse and query investment statements from multiple institutions using natural language.
## Features
- **Multi-Institution Support**: Currently supports Questrade (Interactive Brokers and Scotia coming soon)
- **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
- **Archive Management**: Keeps original PDFs and parsed JSON for reference
## Installation
```bash
# 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
```bash
python -m src.server
```
### Indexing Statements
```python
# Via MCP tool
index_statement("/path/to/statement.pdf")
```
### Querying Data
**Natural Language Search:**
```python
search_statements("What were my total dividends in 2025?", limit=10)
```
**Structured Queries:**
```python
get_holdings_by_symbol("SPY")
get_transactions_by_date("2025-01-01", "2025-09-30")
get_account_balance("51516162", "2025-09-30")
```
### 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
```bash
# 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