Expense Tracker MCP

Expense Tracker MCP

A Model Context Protocol (MCP) server for tracking and managing personal expenses. Built with Python and FastMCP, this server provides tools for adding, viewing, filtering, and summarizing expenses stored in a SQLite database.

Features

• Add Expenses - Record expenses with name, price, category, sub-category, and date
• View All Expenses - Retrieve complete expense history
• Filter by Category - Get expenses for a specific category
• Summarize by Date Range - Calculate total spending between two dates
• SQLite Storage - Persistent, efficient data storage

Requirements

• Python 3.10 or higher
• uv package manager (recommended)

Installation

1. Clone or navigate to the project directory:

   cd expense-tracker-mcp

1. Install dependencies using uv:

   uv sync

Usage

Running the Server

The server uses stdio transport for MCP communication:

uv run python server.py

Available Tools

1. add_expense

Add a new expense to the tracker.

Parameters: | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | name | string | Yes | - | Name/description of the expense | | price | integer | Yes | - | Price amount (in smallest currency unit) | | category | string | Yes | - | Main category (e.g., "Food", "Clothing") | | sub_category | string | No | "" | Sub-category (e.g., "Beverages", "Men's Wear") | | date_added | string | No | auto | ISO format date (e.g., "2026-03-14T19:30:00") |

Example: ``python add_expense("Grocery Shopping", 5000, "Food", "Groceries") add_expense("Movie Ticket", 1200, "Entertainment", "Movies", "2026-03-10T18:00:00") ``

---

2. read_expenses

Retrieve all recorded expenses.

Parameters: None

Returns: List of expense objects

Example Response: ``json [ { "Name": "Grocery Shopping", "Price": 5000, "Category": "Food", "SubCategory": "Groceries", "DateAdded": "2026-03-14T19:30:00" }, { "Name": "Movie Ticket", "Price": 1200, "Category": "Entertainment", "SubCategory": "Movies", "DateAdded": "2026-03-10T18:00:00" } ] ``

---

3. filter_by_category

Get all expenses belonging to a specific category.

Parameters: | Name | Type | Description | |------|------|-------------| | category | string | Category name to filter by |

Example: ``python filter_by_category("Food") ``

Example Response: ``json [ { "Name": "Grocery Shopping", "Price": 5000, "Category": "Food", "SubCategory": "Groceries", "DateAdded": "2026-03-14T19:30:00" } ] ``

---

4. summarize_expenses

Calculate total expenses within a date range.

Parameters: | Name | Type | Description | |------|------|-------------| | start_date | string | Start date in ISO format (e.g., "2026-03-01") | | end_date | string | End date in ISO format (e.g., "2026-03-31") |

Example: ``python summarize_expenses("2026-03-01", "2026-03-31") ``

Example Response: ``json { "StartDate": "2026-03-01", "EndDate": "2026-03-31", "TotalExpenses": 6200, "ExpenseCount": 2 } ``

---

Database Schema

Expenses are stored in a SQLite database (expense_data.db) with the following schema:

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    price INTEGER NOT NULL,
    category TEXT NOT NULL,
    sub_category TEXT,
    date_added TEXT NOT NULL
);

Project Structure

expense-tracker-mcp/
├── server.py           # Main MCP server implementation
├── expense_data.db     # SQLite database (auto-created)
├── expense_data.json   # Legacy JSON file (not used)
├── pyproject.toml      # Project configuration
├── uv.lock             # Dependency lock file
├── .python-version     # Python version (3.10)
└── README.md           # This file

Configuration

pyproject.toml

[project]
name = "expense-tracker-mcp"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "fastmcp>=3.1.0",
]

MCP Integration

This server is designed to work with MCP-compatible clients. Configure your MCP client to connect to this server:

Example Claude Desktop Config: ``json { "mcpServers": { "expense-tracker": { "command": "uv", "args": ["run", "python", "server.py"], "cwd": "/path/to/expense-tracker-mcp" } } } ``

Development

Running Tests

Manual testing can be done using Python:

uv run python -c "
from server import add_expense, read_expenses, filter_by_category, summarize_expenses

# Test adding expenses
add_expense('Test Item', 100, 'Test Category')

# View all expenses
print(read_expenses())

# Filter by category
print(filter_by_category('Test Category'))

# Summarize expenses
print(summarize_expenses('2026-01-01', '2026-12-31'))
"

Adding New Tools

To add new tools to the server:

1. Define a new function with the @server.tool decorator
2. Include type hints for all parameters
3. Add a descriptive docstring
4. Use parameterized SQL queries to prevent injection

Example: ```python @server.tool def my_new_tool(param1: str, param2: int) -> dict: """Description of what this tool does""" conn = get_connection()

... implementation ...

conn.close() return result ```

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request