Cashew Expense Tracker MCP Server

Cashew Expense Tracker MCP Server

Cashew の支出トラッカー SQLite データベースにアクセスできる MCP（Model Context Protocol）サーバーです。このサーバーは、テーブルスキーマをリソースとして公開し、読み取り専用 SQL クエリを実行するツールを提供します。また、一般的なデータ分析タスク向けのプロンプトも用意されています。

特長

• データベーススキーマリソース：すべてのテーブルのスキーマと構造情報にアクセスできます
• 読み取り専用 SQL クエリツール：支出データに対して安全な SELECT クエリを実行できます
• データ分析プロンプト：一般的な支出分析タスク向けの、事前に用意されたプロンプトです
• 複数データベースのサポート：テスト用データベースと本番データベースを切り替えられます
• 安全性を最優先：データを保護するため、読み取り専用の操作のみ許可されます

インストール

このプロジェクトでは、依存関係の管理に uv を使用します。uv がインストールされていることを確認してから、次を実行してください。

uv sync

使い方

サーバーの実行

テスト用データベースで MCP サーバーを起動します。

uv run python cashew_mcp_server.py

メインの Cashew データベースを使用します。

uv run python cashew_mcp_server.py --use-main-db

カスタムのデータベースパスを使用します。

uv run python cashew_mcp_server.py --db-path /path/to/your/database.sqlite

MCP クライアントとの統合

Claude Desktop

Claude Desktop の MCP 設定ファイルにサーバー設定を追加します。

{
  "mcpServers": {
    "cashew-expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "cashew_mcp_server.py"
      ],
      "cwd": "/Users/yash/Developer/cashew-mcp",
      "env": {}
    }
  }
}

VSCode

Vscode ワークスペースの MCP 設定ファイルにサーバー設定を追加します。

{
    "servers": {
        "cashew-mcp-server": {
            "type": "stdio",
            "command": "/Users/yash/Developer/cashew-mcp/.venv/bin/python",
            "args": [
                "/Users/yash/Developer/cashew-mcp/cashew_mcp_server.py",
                "--db-path",
                "/Users/yash/Developer/cashew-mcp/db.sqlite"
            ]
        }
    }
}

MCP Inspector（開発）

MCP Inspector でサーバーをテストします。

uv run mcp dev cashew_mcp_server.py

利用可能なリソース

サーバーは次のリソースを公開します。

データベーススキーマリソース

• cashew://schema - すべてのテーブルを含む完全なデータベーススキーマ
• cashew://schema/{table_name} - 特定のテーブルの詳細なスキーマ

Cashew データベースのテーブルの例：

• wallets - ウォレット／アカウント情報
• categories - 支出と収入のカテゴリー
• transactions - すべての金融取引
• budgets - 予算の定義と上限
• objectives - 財務目標と目的
• category_budget_limits - カテゴリーごとの予算上限

利用可能なツール

SQL クエリツール

1. execute_sql_query(query: str)

   • 読み取り専用の SELECT クエリを実行します
   • 列、行、実行メタデータを含む結果を返します
   • 安全性チェックにより危険な操作を防ぎます

2. get_table_sample(table_name: str, limit: int = 10)

   • 任意のテーブルからサンプル行を取得します
   • データ構造の確認に役立ちます
   • 最大 100 行まで指定できます

3. get_table_count(table_name: str)

   • 任意のテーブルの総行数を取得します
   • データ量をすばやく確認できます

利用可能なプロンプト

データ分析プロンプト

1. analyze_spending_patterns

   • 支出パターンを包括的に分析します
   • カテゴリー別の内訳と傾向
   • 時間経過に伴う支出パターン
   • 予算の達成状況分析

2. budget_analysis

   • 予算の達成状況を評価します
   • 予算と実際の支出を比較します
   • 予算調整に関する提案
   • 今後の予測

3. income_vs_expenses

   • 収入と支出を比較します
   • キャッシュフローを分析します
   • 財務健全性の指標
   • 傾向分析と予測

4. expense_anomaly_detection

   • 通常とは異なる支出パターンを検出します
   • 重複している可能性のある取引を特定します
   • 支出の異常値や外れ値を見つけます
   • 予算超過を検出します

クエリの例

execute_sql_query ツールを使って実行できる SQL クエリの例を以下に示します。

基本的なデータの確認

-- Get recent transactions
SELECT name, amount, date_created, income
FROM transactions
ORDER BY date_created DESC
LIMIT 10;

-- Top spending categories
SELECT c.name, SUM(t.amount) as total_spent, COUNT(*) as transaction_count
FROM transactions t
JOIN categories c ON t.category_fk = c.category_pk
WHERE t.income = 0
GROUP BY c.name
ORDER BY total_spent DESC
LIMIT 10;

-- Monthly spending summary
SELECT
  strftime('%Y-%m', date_created, 'unixepoch') as month,
  SUM(CASE WHEN income = 0 THEN amount ELSE 0 END) as expenses,
  SUM(CASE WHEN income = 1 THEN amount ELSE 0 END) as income,
  COUNT(*) as transactions
FROM transactions
GROUP BY strftime('%Y-%m', date_created, 'unixepoch')
ORDER BY month DESC;

予算分析

-- Current budget status
SELECT
  b.name as budget_name,
  b.amount as budget_amount,
  SUM(t.amount) as spent,
  (b.amount - SUM(t.amount)) as remaining,
  ROUND((SUM(t.amount) / b.amount) * 100, 2) as percent_used
FROM budgets b
LEFT JOIN transactions t ON t.date_created BETWEEN b.start_date AND b.end_date
  AND t.income = 0
WHERE b.archived = 0
GROUP BY b.budget_pk, b.name, b.amount;

カテゴリー分析

-- Average transaction amount by category
SELECT
  c.name as category,
  ROUND(AVG(t.amount), 2) as avg_amount,
  MIN(t.amount) as min_amount,
  MAX(t.amount) as max_amount,
  COUNT(*) as transaction_count
FROM transactions t
JOIN categories c ON t.category_fk = c.category_pk
WHERE t.income = 0
GROUP BY c.name
HAVING COUNT(*) >= 5
ORDER BY avg_amount DESC;

データベーススキーマ

Cashew データベースには、次の主要なテーブルが含まれています。

• wallets：財務を整理するための各種アカウント／ウォレット
• categories：階層構造を持つ収入と支出のカテゴリー
• transactions：金額、日付、カテゴリーを含むすべての金融取引
• budgets：期間と金額を含む予算の定義
• objectives：財務上の目標とターゲット
• category_budget_limits：カテゴリーごとの予算制約

各テーブルには、変更を追跡するための date_created や date_time_modified などの監査フィールドが含まれています。

安全機能

• 読み取り専用アクセス：SELECT クエリのみ許可されます
• クエリ検証：危険な SQL キーワードはブロックされます
• 入力のサニタイズ：すべての入力は実行前に検証されます
• エラー処理：わかりやすいメッセージを伴う適切なエラー処理

開発

サーバーに貢献または変更するには：

1. 依存関係をインストールします：uv sync
2. テストを実行します：uv run python -m pytest（テストが追加された場合）
3. コードをフォーマットします：uv run black .
4. 型をチェックします：uv run mypy .（型ヒントが追加された場合）

トラブルシューティング

よくある問題

1. インポートエラー：仮想環境を適切に有効化するため、uv run を使用してください
2. データベースが見つからない：データベースのパスを確認し、ファイルが存在することを確認してください
3. 権限エラー：SQLite データベースファイルが読み取り可能であることを確認してください

デバッグモード

デバッグ出力を有効にしてサーバーを実行します：

uv run python cashew_mcp_server.py --db-path test.sqlite

サーバーは次の情報を出力します：

• 使用中のデータベースパス
• 見つかった利用可能なテーブル
• 接続状態

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。