finance-intelligence-mcp

Finance Intelligence MCP サーバー

Finance Intelligence MCP は、本番環境に対応した Model Context Protocol (MCP) サーバーです。Claude、Cursor などの AI アシスタントが、自然言語を通じて個人の財務を安全に管理・分析できます。

MIT ライセンスのもとで公開されており、追加の金融ツールで拡張できるよう設計されています。

---

🔍 概要

一般的なクラウドベースの個人向け家計管理アプリとは異なり、Finance Intelligence MCP では、すべての財務データを完全に自分で管理できます。

• アカウント／サブスクリプション不要：SaaS への依存が一切なく、プライベートデータベースに直接接続します。
• テレメトリーゼロ：財務ログが外部の分析 API に送信されることはありません。
• AI による完全なコンテキスト把握：AI アシスタントは、履歴の検索、予算状況の確認、グラフの作成、財務に関する質問への即時回答を行えます。

---

🛠️ アーキテクチャ

   ┌────────────────────────────────┐
   │           MCP Client           │
   │  (Claude Desktop, Cursor, etc) │
   └───────────────┬────────────────┘
                   │
                   │ (STDIO Transport Protocol)
                   ▼
   ┌────────────────────────────────┐
   │  Finance Intelligence Server   │
   │           (Local)              │
   └───────────────┬────────────────┘
                   │
                   │ (Direct SQL Pool Connection)
                   ▼
   ┌────────────────────────────────┐
   │       PostgreSQL Database      │
   │ (Supabase, Local, RDS, etc)    │
   └────────────────────────────────┘

---

✨ 機能

• 支出管理：支出項目の作成、表示、編集、一括削除を行えます。
• マルチレベルの予算設定：overall の支出、特定の category の上限、または階層化された subcategory の目標まで、上限を設定できます。
• 分析の内訳：週次／月次／年次の期間ごとに、カテゴリ、サブカテゴリ、メモ、日付別に支出を集計します。
• ビジュアルチャート：過去の支出を示す Matplotlib の折れ線グラフ／棒グラフを自動生成するツールを提供します。
• Excel スプレッドシートへのエクスポート：長いリストのレスポンスを切り詰め、大規模なデータセットからダウンロード可能な Excel スプレッドシートを生成します。
• 財務健全性スコア：個人財務に関する 6 つの主要 KPI に基づき、決定論的な財務健全性スコアを算出します。

---

⚙️ 要件と互換性

• トランスポート：stdio
• 対応プラットフォーム：
  • Windows
  • macOS
  • Linux
• Python の互換性：Python 3.10、3.11、3.12（テスト済み）
• データベース：PostgreSQL 12 以降（Supabase、RDS、ローカルの Postgres など）
• 対応クライアント：
  • Claude Desktop
  • Cursor
  • stdio をサポートするすべての MCP クライアントと互換性があります。

---

💾 インストールとセットアップ

1. クイックセットアップ（ショートカット）

uv がインストール済みであれば、2 行で開始できます。

git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
cd Finance-Intelligence-MCP
uv sync

2. 詳細なインストール手順

ステップ A：PostgreSQL 接続 URL の取得

最も簡単で無料の方法は、Supabase を利用することです。

1. Supabase にアクセスして、無料プロジェクトを作成します。
2. Project Settings（歯車アイコン）> Database に移動します。
3. Connection string で URI を選択し、文字列をコピーします。
   • 例：postgresql://postgres.[your-project-ref]:[your-password]@aws-0-us-east-1.pooler.supabase.com:5432/postgres
   • （[your-password] をデータベースのパスワードに置き換えてください）。

ステップ B：リポジトリのクローン

コードベースをマシン上のディレクトリにクローンします。

git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
cd Finance-Intelligence-MCP

このディレクトリの絶対パスをコピーします（例：C:/Users/Admin/Desktop/Finance-Intelligence-MCP）。 注：JSON 設定では、パスに必ずスラッシュ（/）を使用してください。

ステップ C：依存関係のインストール

uv がインストールされていない場合は、プロジェクトのメタデータからインストールします。

pip install -e .

---

3. クライアントとの統合

Claude Desktop のセットアップ

1. Claude の設定ファイル（claude_desktop_config.json）を開きます。
   • Windows：Win + R を押し、%APPDATA%\Claude\claude_desktop_config.json を貼り付けて Enter キーを押します。
   • macOS：Finder の「フォルダへ移動」に ~/Library/Application Support/Claude/claude_desktop_config.json を貼り付けます。
2. mcpServers に次のエントリを追加します。

{
  "mcpServers": {
    "finance-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
      }
    }
  }
}

3. 保存し、Claude Desktop を完全に再起動します。

Cursor IDE のセットアップ

1. Settings > Features > MCP に移動します。
2. + Add New MCP Server をクリックします。
   • Name：Finance Intelligence
   • Type：command
   • Command：

     uv --directory "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY" run python main.py
     

3. + Add Env Var をクリックします。
   • Key：DATABASE_URL
   • Value：REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING
4. Save をクリックして更新します。

---

💬 プロンプトの例

設定が完了したら、AI アシスタントに次のように話しかけてみましょう。

• 「今日の昼食代として ₹250 を食費に追加して。」
• 「今月の支出内訳を表示して。」
• 「5 月から 7 月までのすべての支出を Excel レポートにして。」
• 「月間予算の上限を超えていますか？」
• 「今週の外食にいくら使いましたか？」
• 「月間の財務健全性スコアを計算して、フィードバックをください。」
• 「過去 30 日間の支出グラフを作成して。」

---

🛠️ 利用可能なツール

サーバーは、クライアントに 12 個のコアツールを登録します。

ツール名	パラメーター	説明
add_expense	date、amount、category、subcategory、note	新しい支出取引を追加します。
list_expenses	start_date、end_date	取引を一覧表示し、件数が 50 を超える場合は Excel にエクスポートします。
expense_breakdown	start_date、end_date、group_by、breakdown、category、subcategory	支出の合計額と件数を集計します。
delete_expenses	expense_ids、start_date、end_date、category、subcategory	フィルターに一致する支出を削除します。
update_expenses	expense_ids、filter_...、date、amount、category、subcategory、note	支出の記録を編集します。
create_budget	budget_type、amount、period、start_date、end_date、category、subcategory、budgets	新しい支出上限を登録します。
list_budgets	budget_type、category、subcategory、period	登録済みの予算を返します。
update_budgets	budget_ids、filter_...、budget_type、amount、period、start_date、end_date、category、subcategory	有効な予算を変更します。
delete_budgets	budget_ids、start_date、end_date、budget_type、category、subcategory、period	対象の予算上限を削除します。
compare_budget_vs_expenses	reference_date、budget_type、category、subcategory、period	予算と実際の支出を比較します。
expense_summary	period、group_by、category、subcategory、start_date、end_date	Matplotlib の折れ線グラフまたは棒グラフを生成します。
financial_health_score	reference_month	個人の財務に関する 6 つの主要指標を評価します。

---

💡 トラブルシューティング

1. uv: command not found

クライアントが uv を見つけられない場合は、標準の Python を実行するように設定ファイルを更新します。

• リポジトリ内で pip install -e . を実行したことを確認します。
• 設定を更新します。

"finance-intelligence": {
  "command": "python",
  "args": [
    "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY/main.py"
  ],
  "env": {
    "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
  }
}

2. 無効な DATABASE_URL ／ PostgreSQL 接続エラー

• Supabase URI 文字列の [your-password] を実際のデータベースパスワードに置き換えたことを確認します。
• URL 文字列の前後に空白がなく、特殊文字が含まれていないことを確認します。
• Supabase インスタンスがアクティブで、一時停止されていないことを確認します。

3. Claude がサーバーを検出しない

• claude_desktop_config.json のフォルダーパスでは、Windows でもスラッシュ（/）を使用していることを確認します。
• %APPDATA%\Claude\logs\mcp*.log（Windows）または ~/Library/Logs/Claude/mcp*.log（macOS）のログを確認し、起動エラーの詳細を調べます。

---

📁 リポジトリ構成

├── src/                       # Helper packages
│   ├── __init__.py
│   ├── budget.py              # Budget database operations
│   ├── analytics.py           # Breakdown aggregations & Matplotlib routines
│   └── health.py              # KPIs and financial health calculator
├── main.py                    # FastMCP Server application
├── categories.json            # Category mapping catalog
├── pyproject.toml             # Dependencies
├── LICENSE                    # MIT License file
└── README.md                  # This file

---

🤝 コントリビューション

コントリビューション、バグ報告、機能リクエストを歓迎します！ 大規模な変更やプルリクエストを提出する前に、Issue を作成してください。

---

📄 ライセンス

このプロジェクトはMIT Licenseのもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

---

👨‍💻 作者

Ronit Rajput

• ポートフォリオ：https://ronitportfolio-seven.vercel.app/assistant
• GitHub：https://github.com/Ronit-019
• LinkedIn：https://www.linkedin.com/in/ronit-rajput/