Expense Tracker Agent

An AI-powered personal expense tracker that turns natural-language requests into structured database operations. The project combines a responsive Streamlit interface, Claude tool use, an MCP server, and local SQLite storage.

What this project demonstrates

• Agentic, multi-step tool use for real database workflows

• A clean separation between the language model, MCP transport, and data layer

• A direct Claude tool-calling loop without an orchestration framework

• Input validation, scoped assistant behavior, and safe local data handling

• Automated smoke tests and continuous integration

• A responsive user interface for entry, conversation, and spending insights

Related MCP server: Expense Tracker MCP Server

Product features

• Add expenses through a form or a natural-language request

• Store the date, amount, category, and description for each transaction

• Search, update, delete, and summarize expenses through MCP tools

• Review totals, recent transactions, and category-level spending

• Ask the focused financial assistant for database-backed insights

• Keep expense data local in a SQLite file

Architecture

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude never accesses SQLite directly. It selects from the MCP tool schemas, and the server owns every validated database read and write.

Example agent workflows

Technology

Quick start

Requirements:

• Python 3.11 or newer

• An Anthropic API key for the assistant

Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

For macOS or Linux, activate the environment with:

source .venv/bin/activate

Create a local environment file and add ANTHROPIC_API_KEY:

Copy-Item .env.example .env

Create the database schema and starter categories, then launch the app:

python db_setup.py
streamlit run streamlit_app.py

The MCP server uses stdio and starts automatically when a client connects.

Quality checks

Install development dependencies and run the same checks used in CI:

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py exercises all 18 MCP tools and removes its temporary records when the smoke test finishes.

MCP tools

The server exposes 18 tools:

• Category management: list_categories, add_category, rename_category, delete_category, get_category_name

• Expense management: add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• Supporting queries: current_date, find_category, get_expense, expenses_between

Project structure

Configuration

The .env file and expenses.db are excluded from Git. API keys and personal expense data stay outside the repository.

To recreate the database with an empty expenses table:

python db_setup.py --reset