Personal Finance & Investment Agent

A production-ready AI agent for personal finance management, investment tracking, and financial recommendations using MCP (Model Context Protocol), FastAPI, and real-time market data.

Features

• 💰 Expense Tracking - Automatic categorization and budgeting
• 📈 Portfolio Management - Real-time portfolio tracking and analysis
• 🤖 AI Financial Advisor - Personalized investment recommendations
• 📊 Tax Optimization - Tax-loss harvesting and optimization strategies
• 🔔 Smart Alerts - Price alerts and investment notifications
• 🏦 Bank Integration - Connect to Plaid for automatic transaction sync

Tech Stack

• FastAPI - High-performance async API
• MCP (Model Context Protocol) - Agentic AI framework
• Ollama - Local LLM for financial analysis
• PostgreSQL - Transaction and portfolio storage
• Redis - Caching and real-time data
• yfinance - Real-time market data
• Plaid API - Banking integration
• Celery - Background task processing

Architecture

finance-agent/
├── src/
│   ├── agent/
│   │   ├── finance_advisor.py      # Core financial analysis
│   │   ├── portfolio_manager.py    # Portfolio optimization
│   │   ├── expense_tracker.py      # Expense categorization
│   │   ├── tax_optimizer.py        # Tax strategy engine
│   │   └── mcp_server.py           # MCP server implementation
│   ├── api/
│   │   ├── main.py                 # FastAPI application
│   │   └── routes/                 # API endpoints
│   ├── models/
│   │   ├── database.py             # SQLAlchemy models
│   │   └── schemas.py              # Pydantic schemas
│   ├── services/
│   │   ├── market_data.py          # Real-time market data
│   │   ├── plaid_service.py        # Banking integration
│   │   └── notification.py         # Alert system
│   └── utils/
│       ├── calculations.py         # Financial calculations
│       └── indicators.py           # Technical indicators
├── mcp/
│   ├── tools/                      # MCP tool definitions
│   └── prompts/                    # MCP prompt templates
├── alembic/                        # Database migrations
├── tests/
├── requirements.txt
└── docker-compose.yml

Installation

Prerequisites

• Python 3.10+
• PostgreSQL 14+
• Redis 7+
• Ollama (ollama.ai)
• Plaid API keys (optional)

Setup

cd finance-agent

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Setup database
createdb finance_agent
alembic upgrade head

# Pull Ollama model
ollama pull llama3.2

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start services
docker-compose up -d  # PostgreSQL, Redis

# Run API server
uvicorn src.api.main:app --reload

# Run MCP server (separate terminal)
python src/agent/mcp_server.py

Usage

API Endpoints

Track Expense

POST /api/v1/expenses
{
  "amount": 45.50,
  "description": "Grocery shopping",
  "date": "2024-01-15",
  "category": "auto"  # AI auto-categorizes
}

Get Budget Analysis

GET /api/v1/budget/analysis?month=2024-01

Add Investment

POST /api/v1/portfolio/positions
{
  "symbol": "AAPL",
  "quantity": 10,
  "purchase_price": 175.50,
  "purchase_date": "2024-01-10"
}

Get Portfolio Performance

GET /api/v1/portfolio/performance

Ask Financial Question

POST /api/v1/ask
{
  "question": "Should I rebalance my portfolio?",
  "context": "current_holdings"
}

Python Client

from finance_agent import FinanceAgent

# Initialize agent
agent = FinanceAgent(api_key="your_key")

# Track expense with auto-categorization
expense = agent.track_expense(
    amount=125.00,
    description="Dinner at Italian restaurant"
)
print(f"Categorized as: {expense.category}")

# Analyze portfolio
analysis = agent.analyze_portfolio()
print(f"Total Value: ${analysis.total_value:,.2f}")
print(f"Return: {analysis.total_return_pct:.2f}%")
print(f"Risk Score: {analysis.risk_score}/10")

# Get AI recommendations
recommendations = agent.get_recommendations(
    risk_tolerance="moderate",
    investment_horizon="long-term"
)

for rec in recommendations:
    print(f"{rec.action}: {rec.symbol} - {rec.reason}")

# Tax optimization
tax_strategies = agent.optimize_taxes(tax_year=2024)
print(f"Potential Tax Savings: ${tax_strategies.estimated_savings:,.2f}")

MCP Integration

The agent implements MCP for advanced agentic capabilities:

# MCP tools available:
# - get_portfolio_value: Get current portfolio value
# - analyze_stock: Analyze individual stock
# - calculate_risk: Calculate portfolio risk metrics
# - suggest_rebalance: Get rebalancing suggestions
# - find_tax_opportunities: Find tax-loss harvesting opportunities

# Example MCP conversation
from mcp import MCPClient

client = MCPClient("http://localhost:5000")

response = client.send_message(
    "I have $10,000 to invest. I'm 30 years old and want moderate risk. What should I do?"
)

# Agent uses MCP tools to:
# 1. Assess risk tolerance
# 2. Analyze current portfolio
# 3. Research suitable investments
# 4. Generate allocation strategy
# 5. Provide actionable recommendations

Features in Detail

Expense Tracking

• Auto-categorization using AI
• Receipt OCR - Extract data from receipts
• Recurring expense detection
• Budget alerts when overspending
• Category-wise analytics

Portfolio Management

• Real-time tracking with yfinance
• Performance metrics: ROI, Sharpe ratio, alpha, beta
• Asset allocation analysis
• Rebalancing suggestions
• Risk assessment

AI Financial Advisor

• Personalized recommendations based on:
  • Age and income
  • Risk tolerance
  • Investment goals
  • Time horizon
• Market analysis and insights
• Diversification suggestions

Tax Optimization

• Tax-loss harvesting opportunities
• Capital gains optimization
• Retirement account optimization
• Estimated tax calculation

Smart Alerts

• Price alerts (target prices reached)
• Portfolio rebalancing alerts
• Budget warnings
• Market news affecting holdings
• Tax deadline reminders

Configuration

Edit .env:

# Database
DATABASE_URL=postgresql://user:pass@localhost/finance_agent

# Redis
REDIS_URL=redis://localhost:6379/0

# Ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2

# Plaid (optional)
PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_secret
PLAID_ENV=sandbox

# Market Data
ALPHA_VANTAGE_KEY=your_key  # optional

# MCP Server
MCP_HOST=0.0.0.0
MCP_PORT=5000

# Security
JWT_SECRET=your_secret_key
ENCRYPTION_KEY=your_encryption_key

Security Features

• 🔐 End-to-end encryption for financial data
• 🔑 JWT authentication for API access
• 🛡️ Role-based access control
• 📝 Audit logging for all transactions
• 🔒 Encrypted database storage

Performance

• Expense categorization: < 1 second
• Portfolio analysis: 2-3 seconds
• AI recommendations: 5-10 seconds
• Real-time price updates: < 500ms

Testing

# Run all tests
pytest tests/

# Test with coverage
pytest --cov=src tests/

# Test specific module
pytest tests/test_portfolio_manager.py

Deployment

# Docker Compose (recommended)
docker-compose -f docker-compose.prod.yml up -d

# Kubernetes
kubectl apply -f k8s/

# Environment variables
kubectl create secret generic finance-agent-secrets \
  --from-env-file=.env.prod

Roadmap

• [ ] Mobile app (React Native)
• [ ] Cryptocurrency portfolio tracking
• [ ] Multi-currency support
• [ ] Social trading features
• [ ] Advanced ML models for prediction
• [ ] Integration with more banks and brokers

Contributing

See CONTRIBUTING.md

License

MIT License - see LICENSE

Disclaimer

⚠️ Important: This software is for informational purposes only. It does not constitute financial advice. Always consult with a qualified financial advisor before making investment decisions.

Support

• Website: useagenticai.in
• Issues: GitHub Issues
• Email: info@useagenticai.in

---

Built with ❤️ by the AgenticAI team