personal-finance

💰 个人理财 MCP

通过 Model Context Protocol 提供的确定性个人理财工具包——包含 77 个计算器、一个元顾问和实时市场数据，并配有精美的 Web UI。以成熟的金融数学为基础。

在线演示： https://sarveshtalele-personal-finance-mcp.hf.space 连接器 URL： https://sarveshtalele-personal-finance-mcp.hf.space/mcp

演示

▶️ 观看 2 分钟演示 ——用日常语言提问 → 串联工具 → 生成优先级计划。

**公开演示说明：**托管的 Space 是一个共享实例，尽力提供服务（有速率限制， 空闲后可能需要冷启动）。如需大量或私密使用，请在本地运行或自行托管 （参见 docs/HOW_IT_WORKS.md）。

---

概览

大多数理财“助手”都会猜数字，而这个不会。它提供 77 个确定性计算器——相同输入， 每次都得到相同答案——并让大模型将日常语言问题路由到合适的工具。描述你的情况（“我 30 岁， 月收入 ₹1L，想在 60 岁退休”），create_financial_plan 编排器便会串联相关计算器，生成一份 优先级计划。

它基于同一套代码库，以三种方式运行：

• 作为 MCP 服务——连接到 Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端。
• 作为网站——Next.js UI，包含实时计算器、市场仪表板和工具目录。
• 作为托管连接器——部署到 Hugging Face Docker Space；一个 URL 即可提供全部三种功能。

亮点

• 🔢 确定性——纯数学计算，数字不依赖模型推理。
• 🤖 从描述到工具——模型将意图映射到工具；用户无需指定工具名称。
• 🇮🇳 以理论为基础——TVM、债务、PPF/SSY/NSC/EPF、债券、衍生品、MPT 等。
• 🛰️ 实时市场数据——共同基金 NAV（AMFI）、外汇（ECB）、股票报价（Yahoo）——无需 API 密钥。
• 🔒 安全加固——无状态、限流、输入受限的 API，并配有安全标头/CSP。

---

工具目录——77 个工具，13 个类别

类别	工具数	示例
货币时间价值	10	终值/现值、年金、永续年金、EAR、实际回报
投资组合分析	11	CAPM、夏普比率、索提诺比率、特雷诺比率、阿尔法、资产配置、再平衡
理财规划	9	净资产、比率、应急基金、退休、教育、保险
印度小额储蓄	9	PPF、SSY、NSC、KVP、SCSS、RD、FD、EPF
共同基金	7	SIP、SWP、一次性投资与 SIP 对比、CAGR、NAV、费用率影响
债务与贷款	6	EMI、摊销、提前还款、债务整合、投资与提前还款对比
固定收益	6	债券价格、YTM、当前收益率、久期、凸性、零息债券
衍生品	5	期货公允价值、期权收益、看跌-看涨平价、Black-Scholes、贝塔对冲
股票估值	5	DDM、两阶段 DDM、市盈率、DCF、股息收益率
实时市场数据	4	共同基金搜索、实时 NAV、外汇汇率、股票/指数报价
现金流与预算	3	家庭现金流、债务收入比、应急基金
风险评估	1	适配度评分 → 建议的股票/债务配置比例
顾问	1	create_financial_plan——从描述到计划的编排器

可在 /tools 浏览全部工具及其实时说明。

---

快速开始

使用托管连接器（无需安装）

Claude Desktop — 设置 → 连接器 → 添加自定义连接器 → 粘贴：

https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Claude Code

claude mcp add --transport http personal-finance https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Cursor / VS Code — 添加到 mcp.json：

{
  "mcpServers": {
    "personal-finance": {
      "url": "https://sarveshtalele-personal-finance-mcp.hf.space/mcp",
      "transport": "http"
    }
  }
}

从 PyPI 安装（stdio 服务）

pip install personal-finance-mcp     # or: uvx personal-finance-mcp

然后将 Claude Desktop 指向它：

{
  "mcpServers": {
    "personal-finance": { "command": "uvx", "args": ["personal-finance-mcp"] }
  }
}

从源代码在本地运行

git clone https://github.com/sarveshtalele/personal-finance-mcp.git
cd personal-finance-mcp
pip install -e .

# Option A — classic stdio MCP server (offline, no web)
python -m src

# Option B — unified server: website + /mcp connector + /api  (http://localhost:7860)
cd web && npm install && npm run build && cd ..
python -m src.web

对于 stdio，将 Claude Desktop 指向本地进程：

{
  "mcpServers": {
    "personal-finance": { "command": "python", "args": ["-m", "src"] }
  }
}

---

网站

python -m src.web 会在一个端口上提供所有内容：

路径	内容
/	Next.js 网站 — 首页、工具目录、实时计算器、市场仪表板、设置指南
/mcp	基于 streamable-HTTP 的 MCP 服务 — 连接器 URL
/api/*	JSON 端点（工具目录、计算器、实时市场数据）

---

架构

src/
├── server.py            # FastMCP server — registers all tool modules
├── __main__.py          # `python -m src`  (stdio transport)
├── tools/               # pure math fns + per-module register(mcp)
│   ├── tvm.py  debt.py  planning.py  bonds.py  stocks.py  mutual_funds.py
│   ├── portfolio.py  derivatives.py  india_savings.py  cashflow.py
│   ├── risk_profile.py  advisor.py   # advisor = story → plan orchestrator
│   └── marketdata.py    # live AMFI / Frankfurter / Yahoo (keyless)
├── models/              # Pydantic schemas + enums
├── utils/               # output formatters
└── web/                 # unified Starlette server (MCP + /api + static site)
    ├── server.py        # routes, security middleware, calculator registry
    └── __main__.py      # `python -m src.web`  (uvicorn, port 7860)

web/                     # Next.js front-end (static export → web/out)
└── app/                 # home, tools, calculator, dashboard, connect

每个工具文件都会将确定性的纯函数与精简的 @mcp.tool 封装器分开，因此 MCP 服务、网页计算器和测试可以使用相同的函数。

---

安全性

• 无状态 — 无数据库、无会话；每次调用相互独立且可复现。
• 强化的 API — 按 IP 限流、限制请求正文大小，并通过输入验证限制驱动循环的参数（年／月／年龄），以防止拒绝服务攻击。
• 安全标头 — CSP（包含用于 Hugging Face 嵌入内容的 frame-ancestors）、 X-Content-Type-Options、Referrer-Policy、Permissions-Policy；CORS 限制为 不带凭据的 GET/POST。标头中间件在 ASGI 层实现，因此 不会缓冲流式 /mcp（SSE）响应。
• 应用中不含密钥 — 实时数据源公开且无需密钥。

如需报告漏洞，请参阅 SECURITY.md。

---

开发

pip install -e ".[dev]"
pytest -q                       # 119 tests
ruff check .                    # lint
python -m src.web               # run the full stack locally

---

部署

作为 Hugging Face Docker Space 部署，每次推送到 main 时都会从 GitHub 自动同步（参见 .github/workflows/hf-sync.yml）。完整说明 — 本地、Docker 和 Hugging Face 部署 — 请参阅 docs/deployment.md。

---

文档

• docs/HOW_IT_WORKS.md — 概念（MCP、传输方式、语义 路由）、附图的完整架构、端到端请求流程、安全 模型、自行托管／在作品集网站上托管，以及生产级路线图。
• docs/deployment.md — 本地、Docker 和 Hugging Face 部署。
• docs/Architecture.md · docs/testing.md · docs/setup.md

贡献

欢迎贡献 — 请参阅 CONTRIBUTING.md 和 行为准则。适合初次参与的问题：添加计算器（一个纯函数 + 一个 register 封装器 + 一个测试）、改进描述以优化工具路由，或扩展 网页 UI。

---

免责声明

用于说明标准金融公式的教育工具。不构成投资建议。 数值仅供参考；请在做出财务决策前核实。

许可证

MIT — 可免费使用、修改和分发。