MCP 服务器

Personal Expense Tracker MCP

Enables local tracking of personal expenses by adding, listing, summarizing, updating, and deleting expense records stored in a CSV file through an MCP client.

README

Personal Expense Tracker MCP

What This Project Does

Personal Expense Tracker MCP is a simple local MCP server for tracking personal expenses

It stores expense data in a local CSV file

The server gives an MCP client five focused tools

add a new expense
list saved expenses
create a spending summary
update an existing expense
delete an existing expense

The project is made to be simple and easy to run locally

No bank account or external API is needed

Requirements

Before starting make sure you have these installed

Node.js version 20 or newer
npm
Git

Check Node.js

node --version

Check npm

npm --version

Check Git

git --version

Install

1 Clone the repository

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

2 Enter the project folder

cd Personal-Expenses-Tracker

3 Install the packages

npm install

Wait until npm finishes installing the required packages

Data File

Expenses are stored locally in

data/expenses.csv

The CSV file uses these columns

id,amount,category,date,description

Do not change the column names

Run the MCP Server

To start the server run

npm run dev

The server uses standard input and output for MCP communication

It is a local server and does not need a web port

Run MCP Inspector

MCP Inspector is the easiest way to test the tools manually

Run

npm run inspect

A browser window should open with MCP Inspector

If it does not open automatically use the URL shown in the terminal

In Inspector

connect to the server
open the Tools section
choose a tool
enter the input
click Execute Tool
check the result

Available Tools

Tool	What It Does	Main Inputs
`add_expense`	adds a new expense to the CSV file	amount category date description
`list_expenses`	lists saved expenses and can filter them	month category
`get_spending_summary`	calculates spending totals for a month	month
`update_expense`	updates one existing expense	id and at least one expense field
`delete_expense`	deletes one existing expense	id

Tool 1 add_expense

Use add_expense to save a new expense

Inputs

amount

The amount of money spent

It must be a positive number

category

The expense category

Examples

groceries
transport
bills
shopping

The category is stored in lowercase so category names stay consistent

date

The expense date

It must use

YYYY-MM-DD

Example

2026-08-12

The date must also be a real calendar date

This is invalid

2026-99-99

description

Optional short information about the expense

Example

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

A successful request adds the expense to

data/expenses.csv

Tool 2 list_expenses

Use list_expenses to view saved expenses

Without filters

{}

Filter by category

{
  "category": "groceries"
}

Filter by month

{
  "month": "2026-08"
}

Use both filters

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

The month must use

YYYY-MM

The month must be between 01 and 12

This is invalid

2026-99

Tool 3 get_spending_summary

Use get_spending_summary to see a summary of your spending

Example

{
  "month": "2026-08"
}

The result can include

selected month
total amount spent
number of expenses
total spending for each category

Example result

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

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

The real values depend on the data inside data/expenses.csv

Example Prompts

Add an expense

I spent 25 on groceries today

This can use

add_expense

Find expenses

show my grocery expenses for this month

This can use

list_expenses

Check spending

how much did I spend this month

This can use

get_spending_summary

Input Validation

The project checks tool input before using it

Examples of invalid input

negative amount
zero amount
wrong date format
impossible calendar date
invalid month
category that is too long
description that is too long

Invalid input is rejected before it is saved

Test the Schemas

Run

npm run check:schema

A successful result should show

All expense schemas are valid.

Troubleshooting

Problem 1 packages are missing

If you see an error saying a package or module cannot be found run

npm install

Then try again

npm run dev

Problem 2 MCP Inspector does not start

Make sure the packages are installed

npm install

Then run

npm run inspect

If an old Inspector process is still running press

Ctrl + C

Then start Inspector again

Problem 3 TypeScript or schema error

Run

npm run check:schema

If everything is correct you should see

All expense schemas are valid.

If there is an error check the file name and line number shown in the terminal

Fix the error before starting Inspector again

Problem 4 invalid date

A valid date must use

YYYY-MM-DD

Valid example

2026-08-12

Invalid example

2026-99-99

Problem 5 no expenses are returned

Check

data/expenses.csv

Make sure it contains expense rows below the CSV header

If the file only contains the header then an empty result is normal

Project Structure

Important project files

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