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
   

2. 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:

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:

[
  {
    "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:

filter_by_category("Food")

Example Response:

[
  {
    "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:

summarize_expenses("2026-03-01", "2026-03-31")

Example Response:

{
  "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:

{
  "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:

@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