Expense Tracker MCP Server

This project is a lightweight FastMCP server for managing personal expenses and budgets over HTTP. It provides a simple way to store expenses in a local SQLite database, organize them by category, and query spending information through MCP-compatible tools.

What it does

• Tracks expense entries with amounts, dates, and descriptions
• Supports category-based organization using a JSON category list
• Exposes expense-related operations through an MCP server endpoint
• Can be run locally for development or deployed remotely for HTTP access

Users can view their data through MCP clients such as Claude Desktop:

• Ask "show all expenses" to call list_expenses.
• Ask "show my budgets" to call list_budgets.
• Ask for a date range, such as "show expenses from 2026-08-01 to 2026-08-31", to filter the expense list.

Run locally

uv run main.py

The local MCP endpoint is:

http://localhost:8000/mcp

Remote deployment

This project is already configured for a remote HTTP MCP server:

mcp.run(transport="http", host="0.0.0.0", port=port)

The server reads these environment variables:

Variable	Default	Purpose
HOST	0.0.0.0	Network interface to bind
PORT	8000	HTTP port, usually set by the hosting provider
EXPENSE_DB_PATH	./expenses.db	SQLite database path
EXPENSE_CATEGORIES_PATH	./categories.json	Categories JSON path

For FastMCP Cloud, set EXPENSE_DB_PATH to a writable persistent path if your deployment provides one. If you do not set it and the app directory is read-only, the server falls back to a temp directory so writes can succeed, but that data may disappear after the cloud server restarts.

Typical remote start command:

uv run main.py

After deployment, connect your MCP client to:

https://your-domain.example/mcp

Important remote notes

• Use HTTPS for public access.
• Make sure the hosting provider exposes the assigned PORT.
• If you keep SQLite, configure persistent storage and set EXPENSE_DB_PATH to that mounted path. Otherwise the database may reset after redeploys.
• Use the database_status tool from Claude to see the active database path and whether SQLite can be initialized.
• For a public server, add authentication or place it behind a protected gateway before storing real financial data.