Personal Expense Tracker
# Personal Expense Tracker
A simple expense tracking API built with **FastAPI**, **SQLite**, and **FastMCP**.
The project lets you add expenses, view them by date range, and get a quick summary of spending by category.
## Features
* Add a new expense
* Store expenses in SQLite
* Filter expenses by date range
* Get spending totals by category
* Optional category filtering for summaries
* Expose the FastAPI app through an MCP server
## Tech Stack
* Python 3.12+
* FastAPI
* SQLite
* Pydantic
* FastMCP
* uv
## Project Structure
```text
PersonalExpenseTracker/
│
├── main.py # FastAPI application and API routes
├── server.py # FastMCP server
├── categories.json # Expense categories
├── pyproject.toml # Project configuration
├── uv.lock # Locked dependencies
├── .gitignore
└── README.md
```
## Getting Started
Clone the repository:
```bash
git clone https://github.com/bhuvpal/PersonalExpenseTracker.git
cd PersonalExpenseTracker
```
Install dependencies:
```bash
uv sync
```
Run the FastAPI server:
```bash
uv run uvicorn main:app --reload
```
The API will be available at:
```text
http://127.0.0.1:8000
```
FastAPI also provides interactive API documentation at:
```text
http://127.0.0.1:8000/docs
```
## API Endpoints
| Method | Endpoint | Purpose |
| ------ | --------------------- | -------------------------------- |
| GET | `/` | Check if the API is running |
| POST | `/expenses` | Add an expense |
| GET | `/expenses` | Get expenses for a date range |
| GET | `/expenses/summarize` | Get spending summary by category |
### Example Expense
```json
{
"amount": 250,
"date": "2026-09-04",
"category": "Food",
"sub_category": "Lunch",
"note": "Lunch with friends"
}
```
## MCP Server
The project also includes a FastMCP server that exposes the FastAPI application for MCP-based usage.
Run it with:
```bash
uv run python server.py
```
## Database
Expenses are stored locally in a SQLite database.
Each expense contains:
* Amount
* Date
* Category
* Sub-category
* Note
## Why I Built This
I built this project to practice building APIs with **FastAPI** and explore how existing APIs can be exposed through **Model Context Protocol (MCP)**.
## Author
**Bhuv Pal**
GitHub: [@bhuvpal](https://github.com/bhuvpal)
TDQS
Scored across 4 tools
The three core tools (list, add, summarize expenses) target clearly distinct operations. However, the fourth tool 'home' has a vague description that gives no indication of what it does, creating one point of ambiguity.
The three expense tools use verbose auto-generated route-style names with redundant doubled segments and HTTP-method suffixes (e.g. list_expenses_expenses_get), while 'home' follows no pattern at all. The conventions are mixed and unpredictable.
Four tools is on the thin side for an expense tracker, and one of them ('home') appears to be a non-functional placeholder rather than a real capability. The count is borderline but not egregious.
The surface only supports create, list, and summarize; there is no update or delete for expenses, and no filtering or retrieval of a single expense. These are significant lifecycle gaps for an expense tracker.