ExpenseTracker
README.md
# Expense Tracker
A personal expense tracking tool built with [FastMCP](https://github.com/jlowin/fastmcp) that exposes expense management as MCP tools and resources. Expenses are stored locally in a SQLite database (`expenses.db`).
## Features
- **Add expenses** with date, amount, category, subcategory, and notes
- **List expenses** within a date range
- **Summarize spending** by category over any period
- **Categories resource** served from `categories.json` (editable without restart)
## Requirements
- Python ≥ 3.14
- [uv](https://docs.astral.sh/uv/) package manager
## Installation
```bash
uv sync
```
## Usage
```bash
uv run python main.py
```
This starts the MCP server (`ExpenseTracker`). Connect an MCP-compatible client (e.g. Claude Desktop) to use the tools:
| Tool | Description |
|------|-------------|
| `add_expense` | Add a new expense entry |
| `list_expenses` | List expenses in a date range |
| `summarize` | Summarize expenses by category |
### MCP Resource
| URI | Description |
|-----|-------------|
| `expense://categories` | Returns available categories as JSON |
## Project Structure
```
.
├── main.py # MCP server entry point
├── categories.json # Expense category definitions
├── expenses.db # SQLite database (created on first run)
├── src/expense_tracker/ # Package source
├── pyproject.toml # Project metadata and dependencies
└── README.md
```
## License
MIT
TDQS
B3.4/5.0
Scored across 3 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: adding an entry, listing entries, and summarizing entries. There is no overlap or ambiguity between them.
Naming Consistency4/5
The naming follows a verb_noun pattern with add_expense and list_expenses, but summarize breaks the pattern by omitting the noun. This is a minor inconsistency that does not harm usability.
Tool Count5/5
Three tools is well-scoped for a simple expense tracking server. Each tool serves a core function, and the count feels neither bloated nor thin.
Completeness3/5
The server supports creating and reading expenses, but lacks update and delete operations. While summarizing adds value, the missing CRUD capabilities represent a notable gap in the tool surface.
Maintenance
ActivityMaintained
ResponsivenessNo issues