Personal Expense Tracker MCP

このプロジェクトの概要

Personal Expense Tracker MCP は、個人の支出を追跡するためのシンプルなローカル MCP サーバーです。

支出データはローカル CSV ファイルに保存されます。

このサーバーは、MCP クライアントに 5 つの主要なツールを提供します。

• 新しい支出を追加する

• 保存済みの支出を一覧表示する

• 支出のサマリーを作成する

• 既存の支出を更新する

• 既存の支出を削除する

このプロジェクトは、シンプルでローカルで簡単に実行できるように作られています。

銀行口座や外部 API は必要ありません。

Related MCP server: expense-mcp

要件

開始する前に、以下のものがインストールされていることを確認してください。

• Node.js バージョン 20 以降

• npm

• Git

Node.js を確認する

node --version

npm を確認する

npm --version

Git を確認する

git --version

インストール

1. リポジトリをクローンする

git clone https://github.com/MohammadYousef-001/Personal-Expenses-Tracker.git

2. プロジェクトフォルダーに入る

cd Personal-Expenses-Tracker

3. パッケージをインストールする

npm install

npm が必要なパッケージのインストールを完了するまで待ちます。

データファイル

支出はローカルの次の場所に保存されます。

data/expenses.csv

CSV ファイルは次の列を使用します。

id,amount,category,date,description

列名は変更しないでください。

MCP サーバーを実行する

サーバーを起動するには、以下を実行します。

npm run dev

このサーバーは、MCP 通信に標準入力と標準出力を使用します。

ローカルサーバーであるため、Web ポートは必要ありません。

MCP Inspector を実行する

MCP Inspector は、ツールを手動でテストするための最も簡単な方法です。

以下を実行します。

npm run inspect

MCP Inspector が表示されたブラウザウィンドウが開きます。

自動的に開かない場合は、ターミナルに表示された URL を使用します。

Inspector では次の手順を実行します。

1. サーバーに接続する

2. Tools セクションを開く

3. ツールを選択する

4. 入力値を入力する

5. Execute Tool をクリックする

6. 結果を確認する

利用可能なツール

ツール 1 add_expense

新しい支出を保存するには、add_expense を使用します。

入力

amount

支出した金額です。

正の数である必要があります。

category

支出のカテゴリです。

例:

groceries
transport
bills
shopping

カテゴリ名を一定に保つため、カテゴリは小文字で保存されます。

date

支出の日付です。

次の形式を使用する必要があります。

YYYY-MM-DD

例:

2026-08-12

日付は実際の暦日でもある必要があります。

これは無効です。

2026-99-99

description

支出に関する任意の短い情報です。

例

{
  "amount": 25,
  "category": "groceries",
  "date": "2026-08-12",
  "description": "milk and bread"
}

成功したリクエストは、支出を次の場所に追加します。

data/expenses.csv

ツール 2 list_expenses

保存済みの支出を表示するには、list_expenses を使用します。

フィルタなし:

{}

カテゴリで絞り込む:

{
  "category": "groceries"
}

月で絞り込む:

{
  "month": "2026-08"
}

両方のフィルタを使用する:

{
  "month": "2026-08",
  "category": "groceries"
}

月は次の形式を使用する必要があります。

YYYY-MM

月は 01 から 12 の間である必要があります。

2026-99

ツール 3 get_spending_summary

支出のサマリーを確認するには、get_spending_summary を使用します。

例:

{
  "month": "2026-08"
}

結果には次のものが含まれます。

• 選択した月

• 支出した合計金額

• 支出の件数

• 各カテゴリの支出合計

結果の例:

month: 2026-08
total amount: 150
expense count: 4

category totals:
groceries: 80
transport: 30
bills: 40

実際の値は data/expenses.csv 内のデータによって異なります。

プロンプト例

支出を追加する

I spent 25 on groceries today

次を使用できます。

add_expense

支出を探す

show my grocery expenses for this month

次を使用できます。

list_expenses

支出を確認する

how much did I spend this month

次を使用できます。

get_spending_summary

入力の検証

このプロジェクトは、ツール入力を使用前に検証します。

無効な入力の例:

• 負の金額

• ゼロの金額

• 日付形式の誤り

• 存在しない日付

• 無効な月

• 長すぎるカテゴリ

• 長すぎる説明

無効な入力は保存される前に拒否されます。

スキーマをテストする

以下を実行します。

npm run check:schema

成功すると、次のように表示されます。

All expense schemas are valid.

トラブルシューティング

問題 1: パッケージが見つからない

パッケージまたはモジュールが見つからないというエラーが表示された場合は、以下を実行します。

npm install

その後、もう一度試してください。

npm run dev

問題 2: MCP Inspector が起動しない

パッケージがインストールされていることを確認してください。

npm install

その後、以下を実行します。

npm run inspect

古い Inspector プロセスがまだ実行されている場合は、次のキーを押してください。

Ctrl + C

その後、Inspector を再度起動します。

問題 3: TypeScript またはスキーマのエラー

以下を実行します。

npm run check:schema

すべて正しければ、次の結果が表示されます。

All expense schemas are valid.

エラーがある場合は、ターミナルに表示されたファイル名と行番号を確認してください。

エラーを修正してから、Inspector を再度起動します。

問題 4: 日付が無効

有効な日付は次の形式を使用する必要があります。

YYYY-MM-DD

有効な例:

2026-08-12

無効な例:

2026-99-99

問題 5: 支出が返されない

次を確認してください。

data/expenses.csv

CSV ヘッダーの下に支出の行が含まれていることを確認してください。

ファイルにヘッダーしかない場合は、空の結果が正常です。

プロジェクト構成

重要なプロジェクトファイル:

Personal-Expenses-Tracker/
│
├── data/
│   └── expenses.csv
│
├── docs/
│   ├── design.md
│   └── threat-model.md
│
├── examples/
│
├── src/
│   ├── index.ts
│   ├── schemas/
│   ├── tools/
│   └── lib/
│
├── SECURITY.md
├── package.json
└── README.md

セキュリティ

ツールの入力は、信頼できない入力として扱われます。

このプロジェクトは、重要な操作の前に入力を検証します。

支出ファイルのパスはアプリケーションが管理します。

MCP クライアントに返されるエラーは短く保たれます。

詳細なエラーはデバッグ用にローカルのターミナルに残ります。

支出ツールは外部ネットワークリクエストを必要としません。

詳細なセキュリティ情報は次の場所にあります。

SECURITY.md

プロジェクトの適用範囲

このプロジェクトは、小規模なローカル個人支出トラッカーです。

次のものは含まれません。

• 銀行口座との接続

• 銀行情報の自動取り込み

• ユーザーログイン

• クラウドデータベース

• 本格的なグラフィカルアプリケーション

• 財務予測

主な目的は、ローカルの支出追跡に利用できるシンプルな MCP ツールを提供することです。

ライセンス

このプロジェクトは MIT ライセンスを使用しています。

LICENSE を参照してください。