---
title: PortfolioMind
emoji: 📊
colorFrom: gray
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0
short_description: 'MultiAgent MCP - Personal FinAssistant '
tags:
  - mcp-in-action-track-consumer
  - mcp-in-action-track-creative
  - building-mcp-track-consumer
---


# 🤖 PortfolioMind - Multi-Agent Financial Assistant

PortfolioMind is an intelligent multi-agent financial assistant that leverages the Model Context Protocol (MCP) to provide comprehensive financial services through specialized AI agents. 
Built with LangGraph, Google Gemini, and MCP servers, it offers real-time market data, portfolio management, document Q&A, and web search capabilities—all in one unified platform.

Whether you're tracking cryptocurrency trends, analyzing stock performance, or seeking insights from your financial documents, PortfolioMind delivers accurate, actionable intelligence through its orchestrated network of specialized agents. 
Experience the future of financial analysis with a system designed to handle complex queries, synthesize multi-source data, and provide you with the clarity you need to make informed investment decisions.

## 🎯 Overview

PortfolioMind orchestrates multiple specialized AI agents using a ReAct (Reasoning + Acting) supervisor pattern. 
Each agent is equipped with domain-specific tools via MCP servers, enabling them to perform complex financial tasks with high accuracy and context awareness.

## 🏗️ Architecture

### System Architecture
```
┌─────────────────────────────────────────────────────────────┐
│                    Gradio UI Interface                 │
│      (Chat Interface + Document Upload + Voice Agent)  │
└───────────────────────┬─────────────────────────────────────┘
                      │
┌───────────────────────▼─────────────────────────────────────┐
│              ReAct Supervisor (LangGraph)              │
│  • Analyzes queries using reasoning loops              │
│  • Routes to appropriate agents                        │
│  • Synthesizes comprehensive answers                   │
└──────┬───────────┬───────────┬───────────┬──────────────┬───┘
       │          │          │          │             │
┌──────▼────┐ ┌─────▼─────┐ ┌──▼──────┐  ┌─▼─────────┐  ┌─▼────────┐
│  Crypto  │ │  Stock   │ │ Finance │ │    RAG    │ │  Search  │
│   Agent  │ │  Agent   │ │ Tracker │ │   Agent   │ │  Agent   │
└─────┬─────┘ └─────┬─────┘ └────┬────┘  └─────┬─────┘  └─────┬────┘
     │            │            │           │             │
┌─────▼─────────────▼─────────────▼────────────▼──────────────▼──────┐
│                        MCP Servers                            │
│  • CoinGecko MCP (Crypto data)                                │
│  • Alpha Vantage MCP (Stock data)                             │
│  • MCP Toolbox (Database operations)                          │
│  • ChromaDB (Vector database)                                 │
│  • DuckDuckGo MCP (Web search)                                │
└─────────────────────────────────────────────────────────────────────┘
```
### ReAct Pattern Workflow

1. **Think**: Supervisor analyzes the query and determines what information is needed
2. **Act**: Calls appropriate specialized agent(s) to gather information
3. **Observe**: Reviews agent responses and evaluates if more information is needed
4. **Repeat**: Continues reasoning loop until sufficient information is gathered
5. **Synthesize**: Generates comprehensive final answer from all gathered information

## 🤖 Specialized Agents

### 🎤 ReAct Supervisor - Voice Agent

PortfolioMind supports voice interaction through ElevenLabs integration. The same ReAct supervisor orchestrates agents via voice, providing:

- Natural voice conversation
- Real-time agent orchestration
- Comprehensive financial assistance

### 🪙 Crypto Agent
- **Purpose**: Real-time cryptocurrency market data and analysis
- **MCP Server**: CoinGecko MCP Server
- **Capabilities**:
  - Current crypto prices and market data
  - Historical price trends
  - Market cap and volume information
  - Cryptocurrency comparisons
- **LLM**: Google Gemini 2.5 Flash

### 📈 Stock Agent
- **Purpose**: Stock market data, company information, and financial analysis
- **MCP Server**: Alpha Vantage MCP Server
- **Capabilities**:
  - Real-time and historical stock prices
  - Company overview and fundamentals
  - Income statements and balance sheets
  - Technical indicators (RSI, MACD, SMA, EMA)
  - News sentiment analysis
  - Top gainers/losers
- **LLM**: Google Gemini 2.5 Flash

### 💼 Finance Tracker Agent
- **Purpose**: Personal portfolio management and tracking
- **MCP Server**: MCP Toolbox (HTTP server for Cloud SQL)
- **Capabilities**:
  - Add/remove stock transactions (BUY/SELL)
  - View current portfolio holdings
  - Calculate cost basis and realized gains
  - Portfolio performance analysis
  - Transaction history
  - Portfolio allocation visualization
- **Database**: Google Cloud SQL (PostgreSQL)
- **LLM**: Google Gemini 2.5 Flash with structured output

### 📚 RAG Agent
- **Purpose**: Document storage, retrieval, and question answering
- **Vector Database**: ChromaDB Cloud
- **Embeddings**: Google Generative AI (embedding-001)
- **Capabilities**:
  - Upload and process documents (PDF, TXT, DOCX)
  - Semantic search across documents
  - Context-aware Q&A
  - Document chunking with overlap
- **LLM**: Google Gemini 2.5 Flash

### 🔍 Search Agent
- **Purpose**: Web search for current information and news
- **MCP Server**: DuckDuckGo MCP Server
- **Capabilities**:
  - Real-time web search
  - Current events and news
  - General knowledge queries
  - Source citations
- **LLM**: Google Gemini 2.5 Flash

## 🛠️ Technology Stack

### Core Framework
- **LangGraph**: Agent orchestration and workflow management
- **LangChain**: LLM integration and tool management
- **Gradio**: Web UI framework

### LLM & AI
- **Google Gemini 2.5 Flash**: Primary language model for all agents
- **Google Generative AI Embeddings**: For document vectorization

### MCP Integration
- **langchain-mcp-adapters**: Bridge between LangChain and MCP servers
- **mcp**: Official MCP Python SDK

### Data Storage
- **ChromaDB Cloud**: Vector database for RAG
- **Google Cloud SQL (PostgreSQL)**: Portfolio transaction database

### Document Processing
- **PyPDF2**: PDF text extraction
- **python-docx**: DOCX text extraction

### Other Libraries
- **pydantic**: Data validation and structured output
- **python-dotenv**: Environment configuration
- **toolbox-langchain**: MCP Toolbox integration

## 📋 Prerequisites

- Python 3.8+
- Docker (for MCP Toolbox server)
- Google Cloud SQL instance (for Finance Tracker)
- GCP Service Account Credentials
- API Keys:
  - Google API Key (for Gemini)
  - Alpha Vantage API Key (for stock data)
  - CoinGecko API Key (optional, for crypto pro features)
  - ChromaDB API Key, Tenant, and Database (for RAG)

## 🏛️ Project Structure

```
PortfolioMind/
├── src/
│   ├── agents/
│   │   ├── crypto_agent_mcp.py      # Crypto market data agent
│   │   ├── stock_agent_mcp.py       # Stock market data agent
│   │   ├── finance_tracker_agent_mcp.py  # Portfolio management
│   │   ├── rag_agent_mcp.py         # Document Q&A agent
│   │   └── search_agent_mcp.py      # Web search agent
│   ├── core/
│   │   ├── config.py                # Configuration management
│   │   ├── langgraph_supervisor.py  # ReAct supervisor
│   │   └── mcp_client.py           # MCP client utilities
│   └── utils/
│       └── file_processors.py      # Document processing
├── ui/
│   └── gradio_app.py               # Gradio UI application
├── docker/
│   └── Dockerfile                  # Docker configuration
├── database_schema.sql             # PostgreSQL schema
├── requirements.txt                # Python dependencies
└── README.md                       # This file
```

## 🗄️ Database Schema

The Finance Tracker uses PostgreSQL with the following schema:

### Tables

- **stock_transactions**: Stores all BUY/SELL transactions
  - Transaction details (symbol, type, quantity, price, date)
  - Notes and metadata
  
- **portfolio_positions**: Aggregated current positions
  - Calculated from transactions via triggers
  - Cost basis, realized gains, total invested
  
- **portfolio_snapshots**: Historical portfolio value tracking
  - Time-series data for performance analysis
  
- **stock_metadata**: Cached stock information
  - Company name, sector, industry, market cap
  - Reduces API calls

### Features

- **Automatic Position Calculation**: Triggers automatically update positions when transactions change
- **Realized Gains Tracking**: Calculates gains/losses from sales
- **Performance Snapshots**: Historical tracking of portfolio value

## 📝 License

Apache 2.0

---

**Built with ❤️ using LangGraph, MCP, and Google Gemini**