expense-mcp

💰 expense-mcp

MCP サーバーとして利用できる個人向け支出トラッカー — Claude Desktop、Cursor、nanobot、Windsurf、および MCP 互換クライアントで動作します。

---

機能

• 📝 カテゴリーと説明を付けて支出と収入を記録
• 📊 支出の概要 — 今日、週、月、年
• 💳 予算管理 — カテゴリーごとに上限を設定し、80%／100%でアラートを受け取れます
• 🎯 貯蓄目標 — 目標を作成し、視覚的なバーで進捗を確認できます
• 📈 支出に関する分析情報 — 上位カテゴリー、日次平均、支出額が最も多い日
• 🗑️ 安全な削除 — Pydantic ベースの入力確認で削除を確定
• 🔄 デュアルトランスポート — stdio（ローカル）＋ストリーム可能な HTTP（リモート）

---

インストール

# with uv (recommended)
uv pip install git+https://github.com/justfsl50/expense-mcp.git

# with pip
pip install git+https://github.com/justfsl50/expense-mcp.git

# from source
git clone https://github.com/justfsl50/expense-mcp.git
cd expense-mcp
pip install -e .

---

クイックスタート

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）に追加します。

{
  "mcpServers": {
    "expense-mcp": {
      "command": "uv",
      "args": ["run", "expense-mcp"],
      "env": {
        "DATABASE_URL": "sqlite:///expenses.db",
        "CURRENCY": "₹",
        "DEFAULT_USER": "me"
      }
    }
  }
}

Cursor / Windsurf

同じ設定を、それぞれのアプリの MCP 設定に貼り付けます。

nanobot

{
  "mcp": {
    "servers": [{
      "name": "expense-mcp",
      "command": "uv run expense-mcp"
    }]
  }
}

HTTP モード（リモート／複数クライアント）

python server.py http
# Server runs at http://127.0.0.1:8000/mcp

---

環境変数

変数	デフォルト	説明
DATABASE_URL	sqlite:///expenses.db	SQLite または PostgreSQL の URL
CURRENCY	₹	通貨記号
DEFAULT_USER	default	複数ユーザー構成で使用するユーザー ID

PostgreSQL の例：

DATABASE_URL=postgresql://user:pass@localhost:5432/expenses

---

ツール

ツール	説明	読み取り専用
expense_add	支出または収入を保存します	❌
expense_search	テキスト、日付、カテゴリー、金額で絞り込みます	✅
expense_summary	今日／週／月／年の合計	✅
expense_delete	Pydantic による確認プロンプトを表示して削除します	❌
expense_insights	支出パターンと上位カテゴリー	✅
budget_set	月ごとのカテゴリー予算を設定します	❌
budget_list	使用率（%）付きで予算を表示します	✅
goal_create	貯蓄目標を作成します	❌
goal_update	目標に資金を追加します	❌
goal_list	進捗バー付きで目標を表示します	✅

リソース

URI	説明
expense://summary/month	今月の概要
expense://budgets/current	今月の予算
expense://goals/all	すべての貯蓄目標

プロンプト

プロンプト	タイトル	説明
monthly_review	月次レビュー	1か月分の支出を詳しく振り返ります
budget_setup	予算設定	利用履歴から予算を自動提案します
savings_plan	貯蓄計画	貯蓄目標に向けた計画を作成します

---

使用例

MCP クライアントで自然に話しかけるだけです。

"spent 500 on groceries"
"show food expenses this week"
"how much did I spend last month?"
"set food budget to 5000"
"am I within budget?"
"save 1000 toward my iPhone goal"
"give me spending insights"
"delete expense #12"

---

アーキテクチャ

• FastMCP と json_response=True を使用した MCP SDK v1.26.0
• 型付きライフスパン — DB エンジンを AppContext データクラスで管理します
• SQLAlchemy 2.0 — DeclarativeBase、sessionmaker
• Pydantic v2 — 入力検証、入力確認用スキーマ
• ツールアノテーション — readOnlyHint、destructiveHint、idempotentHint
• コンテキストログ — ツール内で ctx.info()、ctx.warning() を使用します

データベーススキーマ

expenses  — id, user_id, amount, category, description, type, date, source, created_at
budgets   — id, user_id, category, amount, month
goals     — id, user_id, name, target, saved, deadline

---

ライセンス

MIT — 無料で使用、変更、配布できます。