ExpenseTracker MCP Server

An MCP server for tracking personal expenses, built with FastMCP 3.x. Expenses are stored in a local SQLite database and accessed asynchronously via aiosqlite.

Requirements

Python >= 3.12
uv
Node.js (only for the MCP Inspector during development)

Setup

git clone <repo-url>
cd Test-Remote-Server
uv sync

Running

Start the server over HTTP:

uv run main.py

The server listens on http://0.0.0.0:8000/mcp. To use a different port, edit the mcp.run(...) call at the bottom of main.py.

Development

Run the server with the MCP Inspector UI:

uv run fastmcp dev inspector main.py

If the default Inspector ports (6274/6277) are taken, pick your own:

uv run fastmcp dev inspector main.py --ui-port 6280 --server-port 6281

Note that uv run is required — the Inspector spawns fastmcp as a child process, and without uv run the virtualenv's Scripts/bin directory is not on PATH.

Tools

Tool	Parameters	Description
`add_expense`	`date`, `amount`, `category`, `subcategory=""`, `note=""`	Add a new expense entry
`list_expenses`	`start_date`, `end_date`	List entries in an inclusive date range
`summarize`	`start_date`, `end_date`, `category=None`	Total and count per category

Dates are YYYY-MM-DD strings.

Resources

URI	Description
`expense:///categories`	Category list as JSON

Categories are read from categories.json next to main.py. If that file is absent, a built-in default list is served instead.

Storage

The SQLite database lives at expenses.db inside the system temp directory; the path is printed at startup. It is created automatically on first run.