NAV Analytics MCP Server (standalone)

A self-contained MCP server that exposes Indian mutual fund NAV analytics as tools, querying parquet data through DuckDB — local files or Azure Blob. No external package or framework of yours is required. The server runs only read-only SELECTs and never fabricates data.

Tested with mcp==1.28.1, duckdb==1.5.4, python-dateutil==2.9.0.post0.

Files

server.py            the MCP server (all tool logic; self-contained)
make_sample_data.py  SYNTHETIC fixture generator — dev/smoke-test only
requirements.txt     pinned deps

Related MCP server: Daito

Install

python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Data

The server expects two parquet sources with this schema:

nav_history     scheme_code VARCHAR, nav_date DATE, nav DOUBLE
scheme_master   scheme_code VARCHAR, scheme_name VARCHAR,
                fund_house VARCHAR, category VARCHAR

Point it at data with environment variables (defaults shown):

NAV_HISTORY_PATH     ./data/nav_history.parquet
SCHEME_MASTER_PATH   ./data/scheme_master.parquet

No data yet? Generate a synthetic fixture to prove the server runs:

python make_sample_data.py      # writes ./data/*.parquet

The fixture is a random walk — not real fund data. Replace it with real AMFI-derived parquet before trusting any number.

Azure Blob. Set a connection string and the paths may be az:// URLs; the server loads DuckDB's azure extension and registers a secret automatically:

export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=...;AccountKey=...;"
export NAV_HISTORY_PATH="az://mycontainer/nav/*.parquet"
export SCHEME_MASTER_PATH="az://mycontainer/scheme_master.parquet"

Run

python server.py                     # streamable HTTP at /mcp (default)
MCP_TRANSPORT=stdio python server.py  # stdio (for local Cursor / Claude Desktop)

The HTTP mode is what you host as a claude.ai custom connector (below). The stdio mode is the original local mode for Cursor / Claude Desktop.

Host it for the team as a claude.ai connector

Goal: your team uses this in the claude.ai web app, plug-and-play — each teammate adds one URL, nobody installs Python or handles the Azure key. That means hosting the server once over HTTPS with OAuth.

1. Rotate the Azure key first

The old .cursor/mcp.json committed a live Storage account key. Rotate it in the Azure portal. The new key goes only into the host's settings below — never into a committed file.

2. Deploy (Azure App Service)

A Dockerfile is included. Build/push the image (or use App Service's build-from-source), then set these application settings:

AZURE_STORAGE_CONNECTION_STRING   <rotated connection string>
NAV_HISTORY_PATH                  az://mfnavdata/processed/nav_history/year=*/*.parquet
SCHEME_MASTER_PATH                az://mfnavdata/processed/scheme_master.parquet
PUBLIC_BASE_URL                   https://<your-app>.azurewebsites.net

App Service terminates HTTPS and injects $PORT automatically.

Auth. Setting PUBLIC_BASE_URL turns on OAuth: the server runs its own self-contained OAuth authorization server (fastmcp's InMemoryOAuthProvider) and advertises the discovery endpoints claude.ai probes — no Azure App Registration, external identity provider, or scope configuration required. claude.ai registers itself dynamically and completes the handshake. Any client that completes the flow is granted access, so this gates on knowing the URL plus the OAuth handshake — appropriate for a small trusted team behind a URL you control. (Tokens are in-memory: a server restart means teammates click "reconnect" once. To add real per-user identity + revocation later, swap in a hosted provider — Google/GitHub/WorkOS — by editing only _build_auth() in server.py.)

If PUBLIC_BASE_URL is unset, the server runs unauthenticated — use that only for local testing, never public hosting.

3. Each teammate adds the connector (one-time)

In claude.ai → Settings → Connectors → Add custom connector → paste:

https://<your-app>.azurewebsites.net/mcp

Complete the Entra sign-in when prompted. The 5 NAV tools then appear in the connector picker in any chat. (Personal claude.ai plans can't push org-wide, so each teammate does this once — but that's the whole setup.)

Register with a local client (stdio)

For local use in Cursor (.cursor/mcp.json) or Claude Desktop (claude_desktop_config.json) — set MCP_TRANSPORT=stdio:

{
  "mcpServers": {
    "nav-analytics": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "NAV_HISTORY_PATH": "/absolute/path/to/data/nav_history.parquet",
        "SCHEME_MASTER_PATH": "/absolute/path/to/data/scheme_master.parquet"
      }
    }
  }
}

Use absolute paths for command, args, and any file paths; MCP clients don't run in your project directory. For Azure, put the connection string in env instead of the local paths.

Tools

• search_funds(query, limit=10) — fuzzy fund-name → scheme_code resolver. Call this first when the user names a fund; feed the resulting code into the returns tools. Returns Regular/Direct and Growth/IDCW variants separately.

• get_fund_returns(scheme_codes, period) — point-to-point return_pct and annualized cagr_pct for one or many funds. cagr_pct is populated only for windows longer than a year (2Y/3Y/5Y, and SI when the fund is >1yr old); it is null for shorter windows.

• get_fund_returns_between(scheme_codes, start_date, end_date) — the same numbers over an explicit ISO YYYY-MM-DD range instead of a named period, for when the user gives actual dates. Unlike the named periods, the window is the same absolute pair for every fund rather than anchored per-fund. Both ends snap to the latest NAV on/before the requested date, so the realized window can be a day or two narrower — read start_nav_date / end_nav_date for what was actually used. cagr_pct follows the realized duration (>1yr). A start_date before a fund's inception gives that fund an error row rather than silently starting at inception.

• get_category_returns(category, period, sort_by, ascending, staleness_days=7) — returns for every fund in a category, ranked, with a staleness guard.

• list_categories() / list_funds_in_category(category) — discovery.

Periods: 1W 2W 1M 3M 6M 9M 1Y 2Y 3Y 5Y YTD MTD SI.

Benchmark indices

Three more tools mirror the fund ones for market indices, so a fund and its benchmark can be compared over an identical window:

• list_indices() — the available indices with ticker, name and history span.

• get_index_returns(tickers, period) — mirrors get_fund_returns: same period strings, same window conventions, same maths.

• get_index_returns_between(tickers, start_date, end_date) — mirrors get_fund_returns_between.

109 indices are covered, with daily closes back to 1990 — broad market (Nifty 50/100/200/500, Midcap, Smallcap, Microcap), sectoral (Bank, IT, Pharma, Auto, FMCG, Metal, Realty, Energy…), factor (Momentum, Quality, Value, Alpha, Low Volatility) and thematic (Defence, Railways, EV, Digital, Tourism).

Tickers are derived from the index name — Nifty Midcap 150 → NIFTY_MIDCAP_150 — and list_indices() advertises the full set. Common shorthands are aliased (NIFTY50, NIFTY500, MIDCAP150, BANKNIFTY, NIFTYIT, SMALLCAP250, VIX, …); any exact ticker works without an alias. The source is NSE-only, so there is no BSE Sensex series.

Index data is committed to this repo, not fetched at runtime — see data/index_history.parquet. The server reads it as a plain local file, so there is no network call in the request path. Two scripts maintain it, both run from the project root:

pip install -r requirements-dev.txt

# Full rebuild from the Weekly Market Pulse Tracker workbook (put it in Index/)
python Index/parse_index_xlsx.py

# Daily top-up from the NSE Index_close_<date>.csv export (put it in Index/)
python Index/append_daily_close.py

git add data/index_history.parquet data/index_master.parquet

The daily script only updates indices already present, is safe to re-run (it skips rows it already has), and writes atomically. The source workbook and CSV are gitignored — only their parquet output is committed, so the data is as current as the last deploy.

Index/fetch_index_data.py is the earlier Yahoo Finance fetcher, kept for ad-hoc use. It is no longer the source of the committed parquet: Yahoo carried 5 indices from 2007, and served the sector indices too sparsely to trust.

Price return vs total return. Index levels from Yahoo are price return — they exclude dividends — while fund NAVs are total return. Comparing them directly flatters the fund by roughly 1–1.5%/yr for Indian equity. Every index response carries return_type: "price"; say so when presenting a fund-vs-benchmark comparison.

Conventions worth knowing

• Per-fund anchor. Every window ends at each fund's own latest NAV, not the calendar today (the latest NAV may lag a day or two; non-trading days have no NAV). This matches how Value Research / ET Money report.

• Full-period start. For trailing windows the start snaps to the latest NAV on/before (anchor − period) so you capture a complete period. YTD/MTD anchor to the first NAV on/after the calendar start; SI starts at inception.

• Staleness. In category queries, a fund whose last NAV lags the category's freshest as-of date by more than staleness_days is flagged stale, kept in the results list, and excluded from avg_return_pct / avg_cagr_pct so the averages never blend mismatched as-of dates.

• One connection. The server opens a single read-only DuckDB connection at startup and holds it for the process lifetime.

Before trusting the numbers

Validate the start-boundary convention against a golden reference: take one real fund, compute 1Y/3Y/5Y, and compare to its published figures for the same as-of date (align the as-of first, or a date mismatch will look like a math bug). If trailing returns come out consistently low, flip the trailing start snap from on/before to on/after (anchor − period) in _resolve_window.