mcp server

mfmcp

Local-first MCP server, CLI, and dashboard for analyzing your Indian mutual-fund portfolio from a CAS PDF: XIRR, LTCG harvesting, SIP/STP detection, overlap.

YashasviAsthana/mfmcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mfmcp": {
      "command": "uvx",
      "args": [
        "mfmcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 27, 2026

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:

A CLI report: one command, a full text report in your terminal. No AI required.
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).
An MCP 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 (recommended):

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:

pip install -e .

Verify: mfmcp --version (or uv run mfmcp --version).

Step 1: Get your CAS

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):

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)

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)

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 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):

claude mcp add mfmcp --scope local -- mfmcp serve

Claude Desktop: add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "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. 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.