経費管理エージェント

AI を活用した個人用経費管理ツールで、自然言語のリクエストを構造化されたデータベース操作に変換します。このプロジェクトは、応答性の高い Streamlit インターフェース、Claude のツール使用、MCP サーバー、およびローカルの SQLite ストレージを組み合わせたものです。

このプロジェクトで実証していること

• 実際のデータベースワークフローのためのエージェント的でマルチステップのツール使用

• 言語モデル、MCP トランスポート、データ層の明確な分離

• オーケストレーションフレームワークを使用しない直接的な Claude ツール呼び出しループ

• 入力検証、スコープ付きアシスタント動作、安全なローカルデータ処理

• 自動化されたスモークテストと継続的インテグレーション

• 入力、会話、支出の洞察のための応答性の高いユーザーインターフェース

Related MCP server: Expense Tracker MCP Server

製品の機能

• フォームまたは自然言語のリクエストを通じて経費を追加

• 各取引の日付、金額、カテゴリ、説明を保存

• MCP ツールを通じて経費の検索、更新、削除、集計

• 合計、最近の取引、カテゴリ別の支出を確認

• 集中型の財務アシスタントにデータベースに基づく洞察を問い合わせ

• 経費データを SQLite ファイルにローカルに保存

アーキテクチャ

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude は SQLite に直接アクセスしません。Claude は MCP ツールスキーマから選択し、サーバーが検証済みのすべてのデータベース読み取りと書き込みを所有します。

エージェントワークフローの例

テクノロジー

クイックスタート

必要条件：

• Python 3.11 以上

• アシスタント用の Anthropic API キー

仮想環境を作成して有効化：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

macOS または Linux の場合、次のコマンドで環境を有効化：

source .venv/bin/activate

ローカル環境ファイルを作成し、ANTHROPIC_API_KEY を追加：

Copy-Item .env.example .env

データベーススキーマとスターターカテゴリを作成し、アプリを起動：

python db_setup.py
streamlit run streamlit_app.py

MCP サーバーは stdio を使用し、クライアントが接続すると自動的に起動します。

品質チェック

開発依存関係をインストールし、CI で使用される同じチェックを実行：

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py は 18 個すべての MCP ツールを実行し、スモークテスト終了時に一時レコードを削除します。

MCP ツール

サーバーは 18 個のツールを公開しています：

• カテゴリ管理: list_categories, add_category, rename_category, delete_category, get_category_name

• 経費管理: add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• サポートクエリ: current_date, find_category, get_expense, expenses_between

プロジェクト構成

設定

.env ファイルと expenses.db は Git から除外されています。API キーと個人の経費データはリポジトリの外部に保持されます。

空の経費テーブルでデータベースを再作成するには：

python db_setup.py --reset