Content
# mfmcp
**v0.1.0** · MIT License · Python 3.11+ · Linux / macOS / Windows
**Your entire Indian mutual-fund portfolio (every AMC, every folio) analyzed on your own
machine, with or without an AI assistant.**
`mfmcp` reads your **CAS (Consolidated Account Statement)** PDF, enriches it with live NAV,
and gives you three ways to use the analysis:
1. **A CLI report**: one command, a full text report in your terminal. No AI required.
2. **An interactive dashboard**: a local web page with growth charts, tax planning, SIP/STP
detection, and more. No AI required (an optional chat panel uses Claude if you have it).
3. **An [MCP](https://modelcontextprotocol.io) server**: 23 tools any AI agent
(Claude Desktop, Claude Code, Cursor, ...) can call in natural language:
*"What's my XIRR? How much LTCG can I harvest tax-free this year?"*
Everything runs locally. Your statement is never uploaded anywhere.
## What it analyzes
- **Returns**: portfolio and per-fund XIRR from your real dated cashflows, absolute gains,
trailing 1/3/5-year CAGR
- **Benchmark alpha**: your actual deposits/withdrawals replayed into a Nifty 50 index fund,
answering: did your fund selection beat just buying the index?
- **Tax planner**: realized/unrealized STCG & LTCG (FIFO), this FY's ₹1.25L equity-LTCG
exemption headroom, loss-offset candidates, and a per-lot calendar of when holdings turn
long-term
- **Allocation**: by asset class, market cap (large/mid/small...), AMC, and category, with
concentration flags
- **SIPs & STPs**: detects systematic investments and inter-fund transfer plans from the
transaction history, including stopped/paused ones
- **Costs & hygiene**: Regular-plan expense drag vs Direct, overlapping funds in the same
sub-category, redemptions left idle
- **Risk**: volatility and max drawdown per fund
- **Health check**: one call that runs everything and returns prioritized findings
## Why a CAS and not a broker API?
A CAS covers **every** AMC and RTA in one free statement: funds bought through any platform,
directly with the AMC, or held in demat. Broker integrations only see what you
bought on that broker.
---
## Install
Requires Python 3.11+. With [uv](https://docs.astral.sh/uv/) (recommended):
```bash
git clone https://github.com/YashasviAsthana/mfmcp.git
cd mfmcp
uv sync # create the venv and install dependencies
uv tool install --editable . # optional: a global `mfmcp` command
```
Or with plain pip:
```bash
pip install -e .
```
Verify: `mfmcp --version` (or `uv run mfmcp --version`).
## Step 1: Get your CAS
```bash
mfmcp fetch
```
This opens the CAMS CAS page in your browser and prints the steps. Request the **Detailed**
"CAS - CAMS + KFintech" statement **from your earliest investment date** (lifetime figures need
full history), set a PDF password, and download the emailed attachment. `mfmcp` watches your
Downloads folder, validates the PDF, and files it away: no manual file handling.
> MF Central's own "Detailed Report" download uses a different PDF format that is not
> parseable yet; use the CAMS route. Full walkthrough: `docs/getting-your-cas.md`.
## Step 2: Store the password (once)
Put your CAS PDF password in a `.env` file in the project directory (gitignored):
```bash
echo "MFMCP_CAS_PASSWORD=your-password" > .env
```
Or export `MFMCP_CAS_PASSWORD` in your environment. After this, no command or AI tool ever
needs the password again: it stays out of prompts, agent conversations, and shell history.
## Step 3: Use it
### A. Terminal report (no AI needed)
```bash
mfmcp analyze
```
Prints the full report: summary, holdings grouped by fund with demat/non-demat lots, XIRR,
allocation, concentration flags, and capital gains.
### B. Interactive dashboard (no AI needed)
```bash
mfmcp dashboard
```
Serves a self-contained page on `127.0.0.1` (localhost only): summary tiles, a prioritized
**health check**, an interactive **growth chart** (hover any date, 1Y/3Y/All ranges), a
**benchmark card**, hoverable allocation donuts (asset class / market cap / AMC), and tabs for
Holdings, Tax planner, LTCG calendar, SIPs & STPs, Overlap & costs, and Risk & returns. Every
table sorts by any column.
The dashboard includes an optional **chat panel** ("which fund is dragging my returns?") backed
by a local, sandboxed [Claude Code](https://claude.com/claude-code) session:
- Needs the `claude` CLI installed; without it, use `--no-chat` (everything else works).
- Sandboxed by a tool denylist: the chat cannot run commands or touch your filesystem.
- It can research the web for fund facts; disable with `--no-web`.
- Your (PII-scrubbed) portfolio data is sent to the model when you chat; `--no-chat` avoids
that entirely.
### C. MCP server (for AI agents)
`mfmcp` (or `mfmcp serve`) runs a standard MCP server over stdio.
**Claude Code** (from the project directory):
```bash
claude mcp add mfmcp --scope local -- mfmcp serve
```
**Claude Desktop**: add to `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
```json
{
"mcpServers": {
"mfmcp": {
"command": "mfmcp",
"args": ["serve"],
"env": { "MFMCP_CAS_PASSWORD": "your-password" }
}
}
}
```
Other clients (Cursor, etc.): any stdio MCP client config works the same way: see
`docs/mcp-clients.md`. Then just talk:
```
Load my CAS at ~/.mfmcp/statements/<file>.pdf
Run a health check. Am I beating the Nifty 50?
How much LTCG can I harvest tax-free this FY? Any stopped SIPs or STPs?
```
## MCP tools
| Tool | What it returns |
| --- | --- |
| `open_cas_portal(portal)` | Open the CAS portal in the browser; returns the steps to follow. |
| `import_downloaded_cas(password, timeout)` | Wait for the downloaded CAS PDF, then load it. |
| `load_cas(path, password)` | Parse a CAS PDF and load it (returns a summary, no PII). |
| `health_check(live, include_benchmark)` | One-call automatic analysis: prioritized findings. |
| `portfolio_summary(live)` | Invested, current value, absolute return, portfolio XIRR. |
| `list_holdings(include_zero, live)` | Per-scheme units, cost, value, gain, XIRR. |
| `portfolio_xirr(live)` / `scheme_xirr(scheme, live)` | Money-weighted annualized returns. |
| `allocation(by, live)` | Weights by `category`, `amc`, `asset_class`, or `market_cap`. |
| `concentration_report(live)` | Flags over-exposure to a single scheme/AMC/category. |
| `capital_gains(fy, method, live)` | Realized + unrealized STCG/LTCG (FIFO worksheet). |
| `tax_harvesting(live)` | Equity-LTCG exemption headroom this FY and loss-offset candidates. |
| `ltcg_calendar()` | When each open lot turns long-term (12mo equity / 36mo other). |
| `sip_analysis(live)` | Detected SIPs: status, cadence, average installment, SIP XIRR. |
| `stp_analysis()` | Detected STPs: transfer routes between funds of one AMC, status, skipped months. |
| `overlap_report(live)` | Funds overlapping in the same sub-category; Regular-plan expense drag. |
| `idle_money()` | Redemptions/payouts never reinvested. |
| `benchmark_comparison(benchmark_amfi_code, live)` | Your cashflows replayed into a benchmark index fund; alpha. |
| `portfolio_growth(step_days)` | Portfolio value + cumulative investment over time. |
| `performance_stats(scheme)` | Trailing 1/3/5-year CAGR, volatility, max drawdown. |
| `nav_lookup(scheme)` / `nav_history(scheme, from, to)` | Latest / historical NAV. |
| `list_transactions(scheme)` | Opt-in raw transaction dump for one scheme. |
`live=True` (default) values the portfolio with live NAV from mfapi.in and degrades gracefully
to the statement's own valuation when offline (with a note saying so).
## Privacy
- Your CAS PDF and parsed data never leave your machine; there is no hosted backend.
- Tool and dashboard outputs are aggregated figures with investor PII (name, PAN, folio
numbers) stripped; line-level transactions are behind one explicit opt-in tool.
- What *does* leave: results of tool calls go to whichever agent/model you connect, and the
optional chat panel sends the PII-scrubbed data blob to the `claude` CLI. Skip the MCP/chat
entirely and nothing is shared with any model.
- Live NAV comes from public endpoints (mfapi.in, AMFI) keyed by public scheme codes only.
## Architecture
```
CAS PDF -> [ingestion] casparser -> normalized Portfolio model
-> [enrichment] AMFI/ISIN -> live + historical NAV (cached on disk)
-> [analysis] pure functions: XIRR, gains, tax, SIP/STP, risk, health
-> [server] FastMCP tools over stdio -> any agent
-> [dashboard] self-contained HTML + local chat backend
```
The analysis core (`mfmcp.analysis`) is pure and never imports casparser or the MCP SDK, so it
doubles as a plain Python library. Run the test
suite (offline, no real data needed) with `uv run pytest`.
## Not financial or tax advice
All output: the capital-gains and tax-harvesting worksheets in particular: exists to help you
understand your portfolio, **not** as filing-ready tax advice. Holding-period rules are
simplified and special cases are not modeled. Verify anything material with a qualified
advisor.
## License
[MIT](LICENSE). All dependencies are permissively licensed, including the PDF backend
(PDFium: BSD/Apache).
## Changelog
**v0.1.0** (2026-07-14): first release: CAS ingestion (CAMS/KFintech detailed), live NAV
enrichment, XIRR/gains/allocation/concentration analysis, tax planner + LTCG calendar, SIP &
STP detection, benchmark alpha, growth time-series, risk stats, health check, 23 MCP tools,
interactive dashboard with optional sandboxed chat, assisted CAS fetching.
