personal-finance

💰 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 種類の決定論的な 計算ツールを搭載しており、同じ入力には毎回同じ答えを返します。また、LLM が自然な言葉で書かれた 質問を適切なツールに振り分けます。「30 歳で、月収は ₹1L、60 歳で退職したい」といった状況を説明すると、create_financial_plan オーケストレーターが関連する計算ツールを連携させ、 優先順位付きの計画にまとめます。

1 つのコードベースで、次の 3 つの方法で実行できます。

• MCP サーバーとして — Claude Desktop、Claude Code、Cursor、または任意の MCP クライアントに接続できます。
• Web サイトとして — ライブ計算ツール、市場ダッシュボード、ツールカタログを備えた Next.js UI を提供します。
• ホスト型コネクターとして — Hugging Face Docker Space にデプロイされ、1 つの URL で 3 つすべてを利用できます。

主な特長

• 🔢 決定論的 — 純粋な数学に基づき、数値の計算にモデル推論は使いません。
• 🤖 ストーリーからツールへ — モデルが意図をツールに対応付けるため、ユーザーがツール名を指定する必要はありません。
• 🇮🇳 理論に基づく — TVM、債務、PPF／SSY／NSC／EPF、債券、デリバティブ、MPT などに対応します。
• 🛰️ ライブ市場データ — 投資信託の NAV（AMFI）、為替（ECB）、株価（Yahoo）を API キーなしで取得できます。
• 🔒 強化されたセキュリティ — ステートレスで、レート制限と入力範囲の制約を備え、セキュリティヘッダー／CSP を適用した API を提供します。

---

ツールカタログ — 13 カテゴリー、77 種類のツール

カテゴリー	ツール数	例
貨幣の時間価値	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	先物の理論価格、オプションの損益、プット・コール・パリティ、ブラック・ショールズ、ベータヘッジ
株式評価	5	DDM、2 段階 DDM、P/E、DCF、配当利回り
ライブ市場データ	4	投資信託検索、ライブ NAV、為替レート、株式／指数の気配値
キャッシュフローと予算管理	3	家計のキャッシュフロー、負債所得比率、予備資金
リスクプロファイリング	1	適合性スコア → 推奨される株式／債券の配分
アドバイザー	1	create_financial_plan — ストーリーから計画を作成するオーケストレーター

ライブの説明とともに、すべてのツールを /tools でご覧いただけます。

---

クイックスタート

ホスト型コネクターを使用する（インストール不要）

Claude Desktop — Settings → Connectors → Add custom connector → 次を貼り付けます：

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 を実行すると、すべてが 1 つのポートで提供されます：

パス	内容
/	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 と Code of Conduct をご覧ください。初めて取り組むのに適した課題：計算機を追加する（純粋関数 + register ラッパー + テスト）、ツールのルーティングを改善するために説明を充実させる、またはウェブ UI を拡張する。

---

免責事項

標準的な金融計算式を説明するための教育用ツールです。投資アドバイスではありません。 数値は例示です。金融上の意思決定を行う前に、必ずご確認ください。

ライセンス

MIT — 自由に使用、変更、配布できます。