MyFinanceMCP — Angel One Portfolio Tracker

A multi-user MCP server and web dashboard for tracking your Angel One portfolio, with AI-powered daily briefings, a trading agent, and ML-based price predictions.

Features

• MCP Server (SSE transport) — connect from Cursor, Claude Desktop, or any MCP-compatible client

• Web Dashboard — browser-based portfolio viewer with login, holdings, positions, orders, and P&L pages

• Finance ADK Agent — chat with the Google ADK finance assistant (Angel One + research tools) via the Agent tab. Requires OPENROUTER_API_KEY on the server

• Trading ADK Agent — risk-aware, proposal-based order execution agent. Analyses prices and technicals; proposes trades but never places orders without explicit approval

• Daily Briefing Scheduler — automatically sends a WhatsApp message each day with per-stock signals (green/yellow/red), LightGBM predictions, and an LLM-written summary of your portfolio

• ML Price Prediction — LightGBM model predicts price direction across 7 timeframes (10 min → 1 year) using technical indicators, price-action features, and sentiment

• Admin API — REST endpoints (/api/admin/*) for registering premium users with Fernet-encrypted Angel credentials and managing their schedules

• Multi-user — each session authenticates with its own Angel One credentials; premium users' credentials are stored encrypted in Postgres

• Zero plaintext credential storage — transient sessions live only in RAM; premium user credentials are encrypted at rest with a Fernet key

Related MCP server: groww-mcp

Project Structure

├── main.py                      # Combined entry point (MCP + Web on one port)
├── mcp_server.py                # MCP FastMCP app (tools: login, portfolio, trading)
├── web_app.py                   # FastAPI web dashboard + briefing schedule API
├── angel_client.py              # Angel One SmartAPI client wrapper
├── session_manager.py           # Per-session client management (in-memory)
│
├── db/                          # Postgres layer (SQLModel + Neon)
│   ├── engine.py                #   Engine, init_db, additive column migrations
│   ├── models.py                #   User, Schedule, Log tables
│   ├── crypto.py                #   Fernet encrypt/decrypt for stored credentials
│   └── __init__.py
│
├── adminApi/                    # Admin REST API (X-Admin-Key protected)
│   ├── router.py                #   /api/admin/users, /api/admin/schedules, /api/admin/logs
│   └── __init__.py
│
├── agents/                      # Google ADK agents
│   ├── factory.py               #   LlmAgent builder (OpenRouter via LiteLLM)
│   ├── finance/                 #   Finance research agent
│   └── trading/                 #   Proposal-based trading agent
│
├── services/                    # Domain logic
│   ├── schedular/               #   Scheduler pipeline
│   │   ├── runner.py            #     APScheduler tick (every 1 min)
│   │   ├── repository.py        #     DB claim / finish (FOR UPDATE SKIP LOCKED)
│   │   ├── job_executor.py      #     Per-schedule pipeline (session → briefing → WhatsApp)
│   │   ├── daily_briefing.py    #     LLM briefing generation (holdings + candles + LightGBM)
│   │   └── whatsapp.py          #     WhatsApp delivery via webhook
│   ├── prediction_service.py    #   LightGBM price-direction predictions
│   ├── ai_service.py            #   OpenRouter AI helpers
│   ├── technical_service.py     #   RSI, MACD, Bollinger, SMA, volume signals
│   ├── fundamental_service.py   #   Fundamental data
│   ├── sentiment_service.py     #   News sentiment scoring
│   ├── sector_service.py        #   Sectoral analysis
│   ├── news_service.py          #   News fetching
│   ├── risk_profile.py          #   User risk profile
│   ├── trade_proposals.py       #   In-memory proposal store for trading agent
│   └── realtime_feed.py         #   Real-time price feed
│
├── integrations/                # Adapters bridging sessions ↔ MCP / local accounts
├── models/                      # LightGBM model training scripts
├── frontend/                    # Jinja2 templates and static assets (CSS, JS)
├── data/                        # JSON data files served under /static/data
├── requirements.txt             # Python dependencies
├── Dockerfile                   # Container definition
└── .env.example                 # Environment variable template

Architecture

One process (main.py) mounts the MCP app under /mcp and the FastAPI web app at / on a single Uvicorn port. The scheduler runs inside the same process (APScheduler async) when SCHEDULER_ENABLED=1.

flowchart TB
  subgraph clients [Clients]
    Browser[Web browser]
    MCPClient[MCP client e.g. Cursor]
    WhatsApp[WhatsApp ← user's phone]
  end

  subgraph server [MyFinanceMCP process]
    Starlette[Starlette / Uvicorn]
    Web[FastAPI web_app]
    MCP[mcp_server FastMCP SSE]
    Admin[adminApi router]
    SM[session_manager in-memory]
    FinanceADK[Finance ADK agent]
    TradingADK[Trading ADK agent]
    Scheduler[APScheduler tick 1 min]
    AngelWrap[angel_client AngelOneClient]
  end

  subgraph db [Postgres / Neon]
    Users[users encrypted creds]
    Schedules[schedules next_run status]
    Logs[logs run history]
  end

  subgraph external [External services]
    AngelAPI[Angel One SmartAPI]
    OR[OpenRouter API]
    WAHook[WhatsApp webhook service]
    Other[yfinance gnews NSE data etc.]
  end

  Browser -->|HTTPS session cookie| Starlette
  MCPClient -->|SSE /mcp/sse| Starlette
  Starlette --> Web
  Starlette --> MCP
  Web --> Admin
  Web --> SM
  Web --> FinanceADK
  Web --> TradingADK
  MCP --> SM
  SM --> AngelWrap
  AngelWrap --> AngelAPI
  FinanceADK --> OR
  TradingADK --> OR
  Web --> Other
  Admin --> db
  Scheduler --> db
  Scheduler -->|run_one| AngelWrap
  Scheduler -->|send| WAHook
  WAHook --> WhatsApp

Request paths

Session flows

• Web login: Browser posts Angel credentials → server creates an AngelOneClient in memory and stores an opaque sid in a signed session cookie.

• Daily briefing: Scheduler ticks every minute → queries schedules for rows where next_run <= now() → claims them with FOR UPDATE SKIP LOCKED → for each claimed schedule: decrypts credentials from users, creates an ephemeral Angel session, generates the briefing, sends WhatsApp, writes to logs, and arms next_run.

• MCP: Client calls the login tool; session stored under a key derived from the MCP connection (id(ctx.session)). Web and MCP logins are separate unless bridged explicitly.

Getting Your Angel One API Credentials

You need 4 credentials from the Angel One SmartAPI portal:

https://smartapi.angelbroking.com/signin

Note: The TOTP secret is only shown once when you enable it. Save it immediately.

Run Locally

1. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

2. Install dependencies

pip install -r requirements.txt

3. Set up Postgres

The scheduler and admin API require a Postgres database. The easiest option for development is a free Neon database. Tables are created automatically on first startup via init_db().

4. Configure environment variables

cp .env.example .env

Edit .env with your values:

Note on two OpenRouter keys: The server OPENROUTER_API_KEY is used by the ADK agents and the daily briefing pipeline. There is a separate optional per-browser OpenRouter key for Dashboard → AI Insights / Ask AI (/api/ai/*) — that is stored only in the browser and never sent to the server's env.

Scaling note: The ADK integration uses in-memory runners in the same process. Use a single Uvicorn worker (the default with python main.py) so chat state and Angel sessions stay consistent.

5. Start the server

python main.py

The server starts on http://localhost:8000:

• Web dashboard: http://localhost:8000/

• Swagger UI: http://localhost:8000/docs

• MCP SSE endpoint: http://localhost:8000/mcp/sse

Daily Briefing Scheduler

The scheduler sends a personalised WhatsApp message to each premium user at their configured time each day. The message includes:

• Per-stock signals (🟢 / 🟡 / 🔴) with price and % changes

• LightGBM 1-day and 1-week direction predictions

• An LLM-written portfolio summary via OpenRouter

How to set it up

1. Create a user via the Admin API (see below).

2. Set a schedule — log in as that user and go to the Trading tab → Daily Briefing, or call POST /api/briefing/schedule with {"time_ist": "08:30"}.

3. Ensure SCHEDULER_ENABLED=1 in your environment and restart.

How it works internally

APScheduler tick (every 1 min)
  └── repository.claim_due_schedules()   ← SQL: next_run <= now(), FOR UPDATE SKIP LOCKED
        └── job_executor.run_one(claim)
              ├── Load user + decrypt credentials (Fernet)
              ├── Create ephemeral Angel session
              ├── generate_daily_briefing()  ← holdings + candles + LightGBM + LLM
              ├── whatsapp.send()            ← POST to webhook service
              ├── Write Log row
              └── finish_schedule()          ← advance next_run by interval_minutes

Admin API

All endpoints require the X-Admin-Key: <your ADMIN_API_KEY> header. Browse to /docs for interactive Swagger UI.

Example: register a user

curl -X POST http://localhost:8000/api/admin/users \
  -H "X-Admin-Key: admin123" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_number": "918107037133",
    "angel_api_key": "Z0hsKZYf",
    "angel_client_id": "PPSU16696",
    "angel_password": "8107",
    "angel_totp_secret": "FP4O3EVUYXZ5Q3WTF6I7JR772Y"
  }'

Connect from an MCP Client

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "angelone-portfolio": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

Then call the login tool with your Angel One credentials to start a session.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "angelone-portfolio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp/sse"]
    }
  }
}

ChatGPT Desktop

Go to Settings → Beta features → MCP Servers → Add Server and enter:

• Command: npx

• Arguments: -y mcp-remote http://localhost:8000/mcp/sse

Available MCP Tools

Deploy to Railway (Recommended)

1. Push this repo to GitHub

2. Go to railway.app and create a new project

3. Connect your GitHub repository

4. Railway auto-detects the Dockerfile and deploys

5. Set the following environment variables in Railway:

   • DATABASE_URL (Postgres connection string)

   • ENCRYPTION_KEY

   • ADMIN_API_KEY

   • OPENROUTER_API_KEY

   • SCHEDULER_ENABLED=1

   • SESSION_SECRET

6. Get your public URL (e.g. https://myfinancemcp.up.railway.app)

After Deployment

Web users: Visit https://your-app.up.railway.app and log in with Angel One credentials.

MCP users: Update the url in your MCP client config:

{
  "mcpServers": {
    "angelone-portfolio": {
      "url": "https://your-app.up.railway.app/mcp/sse"
    }
  }
}

Deploy to Render (Free Tier)

1. Push to GitHub

2. Go to render.com, create a new Web Service

3. Connect your repo, select Docker as the runtime

4. Set all required environment variables (same list as Railway above)

5. Deploy

Note: Render free tier spins down after inactivity. The scheduler resumes when the service wakes up, but will immediately fire all overdue schedules on the next tick.

Security

What lives where

Practices reflected in the app

• Transient Angel credentials are never persisted by the application; they live in RAM for the session lifetime.

• Stored premium credentials are Fernet-encrypted at rest; the raw values are only decrypted in the scheduler worker for the duration of a briefing run and then discarded.

• Web-backed Angel sessions expire after 8 hours (SESSION_TTL_SECONDS in session_manager.py).

• The FOR UPDATE SKIP LOCKED pattern in repository.py makes the scheduler safe to run across multiple replicas, though only one process should have SCHEDULER_ENABLED=1.

• Terminate TLS at the edge for public deployments (Railway, Render, etc.).

Operational cautions

• Lock down .env (file permissions, no commits) and use platform secret stores in production.

• Dashboard "Save OpenRouter key" keeps ciphertext in localStorage — treat the device as trusted.

• Provider rate limits (Angel, OpenRouter, news APIs) still apply; heavy polling can trigger throttling.

• The TOTP secret stored in the DB allows the scheduler to generate TOTP codes autonomously. Treat it with the same sensitivity as a password.

License

MIT