{
  "markdown": "# 💰 Personal Finance MCP\n\n> Deterministic personal-finance toolkit exposed over the **Model Context Protocol** — 77 calculators, a meta-advisor, and live market data, with a polished web UI. Grounded in established financial mathematics.\n\n<!-- mcp-name: io.github.sarveshtalele/personal-finance -->\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org)\n[![MCP](https://img.shields.io/badge/MCP-streamable--http-blueviolet)](https://modelcontextprotocol.io/)\n[![Tests](https://img.shields.io/badge/tests-137_passing-brightgreen)](tests/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Live on Hugging Face](https://img.shields.io/badge/demo-Hugging%20Face-yellow?logo=huggingface&logoColor=white)](https://huggingface.co/spaces/sarveshtalele/personal-finance-mcp)\n\n**Live demo:** https://sarveshtalele-personal-finance-mcp.hf.space\n**Connector URL:** `https://sarveshtalele-personal-finance-mcp.hf.space/mcp`\n\n## Demo\n\n[![Watch the demo](https://img.youtube.com/vi/G27KlYvo6SE/maxresdefault.jpg)](https://youtu.be/G27KlYvo6SE)\n\n▶️ **[Watch the 2-minute demo](https://youtu.be/G27KlYvo6SE)** — plain-language question → chained tools → a prioritized plan.\n\n> **Public demo note:** the hosted Space is a shared, best-effort instance (rate-limited,\n> may cold-start after idle). For heavy or private use, run it locally or self-host\n> (see [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)).\n\n---\n\n## Overview\n\nMost finance \"assistants\" guess at numbers. This one doesn't. It ships **77 deterministic\ncalculators** — same inputs, same answer, every time — and lets an LLM route a plain-language\nquestion to the right tools. Describe your situation (\"I'm 30, earn ₹1L/month, want to retire\nat 60\") and the `create_financial_plan` orchestrator chains the relevant calculators into a\nsingle prioritised plan.\n\nIt runs three ways from one codebase:\n\n- **As an MCP server** — connect it to Claude Desktop, Claude Code, Cursor, or any MCP client.\n- **As a website** — a Next.js UI with a live calculator, a market dashboard, and a tool catalog.\n- **As a hosted connector** — deployed to a Hugging Face Docker Space; one URL does all three.\n\n### Highlights\n\n- 🔢 **Deterministic** — pure math, no model inference for the numbers.\n- 🤖 **Story → tools** — the model maps intent to tools; users never name them.\n- 🇮🇳 **Theory-grounded** — TVM, debt, PPF/SSY/NSC/EPF, bonds, derivatives, MPT, and more.\n- 🛰️ **Live market data** — mutual-fund NAVs (AMFI), FX (ECB), equity quotes (Yahoo) — no API keys.\n- 🔒 **Hardened** — stateless, rate-limited, input-bounded APIs with security headers/CSP.\n\n---\n\n## Tool catalog — 77 tools, 13 categories\n\n| Category | Tools | Examples |\n|----------|:----:|----------|\n| Time Value of Money | 10 | future/present value, annuity, perpetuity, EAR, real return |\n| Portfolio Analytics | 11 | CAPM, Sharpe, Sortino, Treynor, alpha, allocation, rebalancing |\n| Financial Planning | 9 | net worth, ratios, emergency fund, retirement, education, insurance |\n| Small Savings (India) | 9 | PPF, SSY, NSC, KVP, SCSS, RD, FD, EPF |\n| Mutual Funds | 7 | SIP, SWP, lumpsum-vs-SIP, CAGR, NAV, expense-ratio impact |\n| Debt & Loans | 6 | EMI, amortization, prepayment, consolidation, invest-vs-prepay |\n| Fixed Income | 6 | bond price, YTM, current yield, duration, convexity, zero-coupon |\n| Derivatives | 5 | futures fair value, option payoff, put-call parity, Black-Scholes, beta hedge |\n| Equity Valuation | 5 | DDM, two-stage DDM, P/E, DCF, dividend yield |\n| Live Market Data | 4 | MF search, live NAV, FX rate, stock/index quote |\n| Cash Flow & Budgeting | 3 | household cash flow, debt-to-income, contingency fund |\n| Risk Profiling | 1 | suitability score → suggested equity/debt split |\n| Advisor | 1 | `create_financial_plan` — the story → plan orchestrator |\n\nBrowse them all (with live descriptions) at [`/tools`](https://sarveshtalele-personal-finance-mcp.hf.space/tools).\n\n---\n\n## Quick start\n\n### Use the hosted connector (no install)\n\n**Claude Desktop** — Settings → Connectors → Add custom connector → paste:\n\n```\nhttps://sarveshtalele-personal-finance-mcp.hf.space/mcp\n```\n\n**Claude Code**\n\n```bash\nclaude mcp add --transport http personal-finance https://sarveshtalele-personal-finance-mcp.hf.space/mcp\n```\n\n**Cursor / VS Code** — add to `mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"personal-finance\": {\n      \"url\": \"https://sarveshtalele-personal-finance-mcp.hf.space/mcp\",\n      \"transport\": \"http\"\n    }\n  }\n}\n```\n\n### Install from PyPI (stdio server)\n\n```bash\npip install personal-finance-mcp     # or: uvx personal-finance-mcp\n```\n\nThen point Claude Desktop at it:\n\n```json\n{\n  \"mcpServers\": {\n    \"personal-finance\": { \"command\": \"uvx\", \"args\": [\"personal-finance-mcp\"] }\n  }\n}\n```\n\n### Run locally from source\n\n```bash\ngit clone https://github.com/sarveshtalele/personal-finance-mcp.git\ncd personal-finance-mcp\npip install -e .\n\n# Option A — classic stdio MCP server (offline, no web)\npython -m src\n\n# Option B — unified server: website + /mcp connector + /api  (http://localhost:7860)\ncd web && npm install && npm run build && cd ..\npython -m src.web\n```\n\nFor stdio, point Claude Desktop at the local process:\n\n```json\n{\n  \"mcpServers\": {\n    \"personal-finance\": { \"command\": \"python\", \"args\": [\"-m\", \"src\"] }\n  }\n}\n```\n\n---\n\n## The website\n\n`python -m src.web` serves everything on one port:\n\n| Path | What |\n|------|------|\n| `/` | Next.js site — home, tool catalog, live calculator, market dashboard, setup guide |\n| `/mcp` | MCP server over **streamable-HTTP** — the connector URL |\n| `/api/*` | JSON endpoints (tool catalog, calculators, live market data) |\n\n---\n\n## Architecture\n\n```\nsrc/\n├── server.py            # FastMCP server — registers all tool modules\n├── __main__.py          # `python -m src`  (stdio transport)\n├── tools/               # pure math fns + per-module register(mcp)\n│   ├── tvm.py  debt.py  planning.py  bonds.py  stocks.py  mutual_funds.py\n│   ├── portfolio.py  derivatives.py  india_savings.py  cashflow.py\n│   ├── risk_profile.py  advisor.py   # advisor = story → plan orchestrator\n│   └── marketdata.py    # live AMFI / Frankfurter / Yahoo (keyless)\n├── models/              # Pydantic schemas + enums\n├── utils/               # output formatters\n└── web/                 # unified Starlette server (MCP + /api + static site)\n    ├── server.py        # routes, security middleware, calculator registry\n    └── __main__.py      # `python -m src.web`  (uvicorn, port 7860)\n\nweb/                     # Next.js front-end (static export → web/out)\n└── app/                 # home, tools, calculator, dashboard, connect\n```\n\nEach tool file keeps deterministic pure functions separate from the thin `@mcp.tool`\nwrappers, so the same functions power the MCP server, the web calculators, and the tests.\n\n---\n\n## Security\n\n- **Stateless** — no database, no sessions; every call is independent and reproducible.\n- **Hardened API** — per-IP rate limiting, request-body cap, and input validation that\n  bounds loop-driving parameters (years/months/age) to prevent denial-of-service.\n- **Security headers** — CSP (with `frame-ancestors` for the Hugging Face embed),\n  `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`; CORS limited to\n  GET/POST without credentials. The header middleware is implemented at the ASGI layer so\n  it never buffers the streaming `/mcp` (SSE) responses.\n- **No secrets in the app** — live-data sources are public and keyless.\n\nSee [SECURITY.md](SECURITY.md) to report a vulnerability.\n\n---\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest -q                       # 119 tests\nruff check .                    # lint\npython -m src.web               # run the full stack locally\n```\n\n---\n\n## Deployment\n\nDeployed as a **Hugging Face Docker Space**, auto-synced from GitHub on every push to `main`\n(see [`.github/workflows/hf-sync.yml`](.github/workflows/hf-sync.yml)). Full instructions —\nlocal, Docker, and Hugging Face — are in [docs/deployment.md](docs/deployment.md).\n\n---\n\n## Documentation\n\n- **[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)** — concepts (MCP, transports, semantic\n  routing), full architecture with diagrams, end-to-end request flows, the security\n  model, **hosting it yourself / on a portfolio site**, and a production-grade roadmap.\n- [docs/deployment.md](docs/deployment.md) — local, Docker, and Hugging Face deployment.\n- [docs/Architecture.md](docs/Architecture.md) · [docs/testing.md](docs/testing.md) · [docs/setup.md](docs/setup.md)\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the\n[Code of Conduct](CODE_OF_CONDUCT.md). Good first issues: add a calculator (a pure function +\na `register` wrapper + a test), improve descriptions for better tool routing, or extend the\nweb UI.\n\n---\n\n## Disclaimer\n\nEducational tool for illustrating standard financial formulas. **Not investment advice.** Figures\nare illustrative; verify before making financial decisions.\n\n## License\n\n[MIT](LICENSE) — free to use, modify, and distribute.\n",
  "bytes": 9098,
  "sha": "028c8d006cd9a537b97a1d9a5791121e890812a0cf987e1a37bf9158def64705",
  "repo_slug": "sarveshtalele/personal-finance-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sarveshtalele_personal_finance_107c6319/readme"
}