Personal Expense Tracker MCP

# 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

Related MCP server: expense-mcp

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

1. connect to the server

2. open the Tools section

3. choose a tool

4. enter the input

5. click Execute Tool

6. check the result

Available Tools

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

Security

Tool input is treated as untrusted input

The project validates input before important operations

The expense file path is controlled by the application

Errors returned to the MCP client are kept short

More detailed errors stay in the local terminal for debugging

The expense tools do not require external network requests

More security information is available in

SECURITY.md

Project Scope

This project is a small local personal expense tracker

It does not include

• bank account connections

• automatic bank imports

• user login

• cloud database

• full graphical application

• financial forecasting

The main goal is to provide simple MCP tools for local expense tracking

License

This project uses the MIT License

See LICENSE