# Portfolio Copilot

> An AI-powered portfolio analysis assistant for Zerodha Kite users, built to learn MCP + LLM + RAG + Agentic AI fundamentals

- **Type:** MCP server
- **Install:** `agentstack add mcp-mohdasif2294-portfolio-copilot`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mohdasif2294](https://agentstack.voostack.com/s/mohdasif2294)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mohdasif2294](https://github.com/mohdasif2294)
- **Source:** https://github.com/mohdasif2294/portfolio-copilot

## Install

```sh
agentstack add mcp-mohdasif2294-portfolio-copilot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Portfolio Copilot

[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://ollama.ai/)
[](https://www.anthropic.com/)
[](https://kite.zerodha.com/)

> Ask questions about your portfolio in plain English. Get intelligent analysis powered by multiple LLM providers.

## Features

| | Feature | Description |
|---|---------|-------------|
| 📊 | **Portfolio Analysis** | Identify your best/worst performers with news context |
| 🔍 | **Stock Research** | Get comprehensive research on any stock |
| 📈 | **Market Context** | Understand why your portfolio moved today |
| 💰 | **Fundamental Analysis** | Buy/hold/sell recommendations using screener.in data |
| 👀 | **Watchlist Suggestions** | Discover stocks based on your investment style |
| 📅 | **Corporate Events** | Board meetings, dividends, acquisitions, earnings from BSE |

## Quick Start

```bash
# Clone and install
git clone https://github.com/mohdasif2294/portfolio-copilot.git
cd portfolio-copilot
poetry install

# Configure
cp .env.example .env
# Edit .env to set your preferred LLM provider (see below)

# Run
make web    # Web interface at http://localhost:8501
# or
make cli    # Terminal interface
```

**Prerequisites:** Python 3.12+, [Poetry](https://python-poetry.org/docs/#installation)

### LLM Provider Setup

Choose between **Ollama** (local, free) or **Claude** (API, paid):

#### Option 1: Ollama (Default - Local & Free)

```bash
# Install Ollama from https://ollama.ai
ollama pull llama3

# Run (uses Ollama by default)
make cli
```

#### Option 2: Claude (Anthropic API)

```bash
# Set in .env
LLM_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-xxx

# Or use CLI flag
python -m src.ui.cli --provider claude
```

#### CLI Options

```bash
# Use Ollama with a specific model
python -m src.ui.cli --provider ollama --model llama3.1

# Use Claude
python -m src.ui.cli --provider claude

# Override model
python -m src.ui.cli --provider claude --model claude-sonnet-4-20250514
```

---

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Screenshots](#screenshots)
- [Usage](#usage)
- [Agents](#agents)
- [Architecture](#architecture)
- [Tech Stack](#tech-stack)
- [License](#license)

## Screenshots

### Web Interface

*Chat interface with suggested prompts, Kite login sidebar, and real-time responses*

### CLI Interface

*Terminal-based interface with rich formatting and command support*

## Usage

### Natural Language

Just ask questions naturally - the system auto-detects intent:

```
You> What are my worst performing stocks?
You> Tell me about Reliance
You> Why is my portfolio down today?
You> Is TCS a good buy?
You> Suggest stocks for my watchlist
You> Show events for Reliance
You> Any board meetings for Infosys?
```

### Commands

| Command | Description |
|---------|-------------|
| `login` | Connect to your Zerodha account |
| `holdings` | View portfolio table |
| `analyze` | Portfolio analysis |
| `research` | Stock research |
| `fundamentals` | Fundamental analysis |
| `events` | Corporate events from BSE |
| `ingest` | Index news articles |
| `help` | Show all commands |

## Agents

The system uses specialized AI agents for different tasks:

| Agent | What It Does |
|-------|--------------|
| 📊 **Portfolio Analysis** | Analyzes holdings, identifies best/worst performers, fetches relevant news |
| 🔍 **Stock Research** | Researches individual stocks with price data, news, and your position |
| 📈 **Market Context** | Explains why your portfolio moved using market news and trends |
| 👀 **Watchlist Suggestion** | Recommends stocks based on your current sectors and blue chips |
| 💰 **Fundamental Analysis** | Evaluates stocks using screener.in metrics (P/E, ROE, debt) with buy/hold/sell scores |
| 📅 **Corporate Events** | Fetches board meetings, dividends, acquisitions, earnings announcements from BSE India |

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│              User Interface Layer                           │
│  ┌─────────────────────┐    ┌─────────────────────┐         │
│  │  Web UI (Streamlit) │    │   CLI (Rich)        │         │
│  │  - Chat interface   │    │   - Commands        │         │
│  │  - Suggested prompts│    │   - REPL interface  │         │
│  │  - Login sidebar    │    │                     │         │
│  └─────────────────────┘    └─────────────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   Agent Orchestrator                        │
│            (Query detection & routing)                      │
└────────┬─────────────┬─────────────┬─────────────┬──────────┘
         │             │             │             │
         ▼             ▼             ▼             ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ Portfolio │ │  Stock    │ │  Market   │ │Fundamental│ │  Stock    │
│ Analysis  │ │ Research  │ │  Context  │ │ Analysis  │ │  Events   │
│  Agent    │ │  Agent    │ │  Agent    │ │  Agent    │ │  Agent    │
└───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘
       │            │             │             │             │
       └────────────┴──────┬──────┴─────────────┴─────────────┘
                           │
       ┌───────────────┬───┼──────────────-----------─┐
       │               │              │               │
       ▼               ▼              ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  Kite MCP   │ │ RAG System  │ │ Screener.in │ │  BSE India  │
│  (Holdings, │ │ (ChromaDB + │ │ (Fundamental│ │ (Corporate  │
│   Quotes)   │ │  News)      │ │  Data)      │ │  Events)    │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   LLM Provider  │
                    │  ┌───────────┐  │
                    │  │  Ollama   │  │
                    │  │ (Default) │  │
                    │  └───────────┘  │
                    │  ┌───────────┐  │
                    │  │  Claude   │  │
                    │  │ (Optional)│  │
                    │  └───────────┘  │
                    └─────────────────┘
```

## Tech Stack

| Component | Technology |
|-----------|------------|
| Language | Python 3.12 |
| LLM | Ollama (Llama 3) or Claude (Anthropic) |
| Agent Framework | LangGraph |
| Vector Database | ChromaDB |
| Embeddings | Sentence Transformers (all-MiniLM-L6-v2) |
| Broker Integration | Zerodha Kite MCP |
| Web UI | Streamlit |
| CLI | Rich |
| Web Scraping | BeautifulSoup4, httpx |
| Logging | structlog (structured events, console + JSON) |
| Observability | LangSmith (LangGraph tracing), custom tracing decorators |
| Market Data | BSE India API (corporate events) |
| Symbol Resolution | NSE equity list (2200+ stocks, auto-cached) |

## Why This Project?

This is a learning project to understand modern AI systems:
- **MCP (Model Context Protocol)** - Broker data integration
- **RAG (Retrieval Augmented Generation)** - News context
- **LangGraph** - Agentic workflows
- **LLM Orchestration** - Tool calling and synthesis
- **Multi-Provider Support** - Abstraction layer for local (Ollama) and API (Claude) models

---

## License

MIT License - see [LICENSE](LICENSE) for details.

**Disclaimer:** This tool is for **educational purposes only**. It is NOT investment advice. Always consult a qualified financial advisor before making investment decisions.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mohdasif2294](https://github.com/mohdasif2294)
- **Source:** [mohdasif2294/portfolio-copilot](https://github.com/mohdasif2294/portfolio-copilot)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mohdasif2294-portfolio-copilot
- Seller: https://agentstack.voostack.com/s/mohdasif2294
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.