RohitBind123/expense-tracker-mcp-server

Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking and managing personal expenses using FastMCP and SQLite.

Overview

This expense tracker allows you to record, list, and summarize your expenses through a simple MCP interface. It uses SQLite for data persistence and provides tools for adding expenses, querying expenses within date ranges, and generating category-based summaries.

Features

• 📝 Add Expenses: Record expenses with date, amount, category, subcategory, and notes
• 📊 List Expenses: Query expenses within specific date ranges
• 📈 Summarize by Category: Get total spending summaries grouped by category
• 💾 SQLite Database: Lightweight local storage for all expense data
• 🔧 MCP Integration: Works seamlessly with Claude and other MCP clients

Installation

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended) or pip

Setup

1. Clone this repository:

git clone https://github.com/RohitBind123/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

2. Install dependencies:

uv sync

Or with pip:

pip install -r requirements.txt

Usage

Running the Server

python main.py

Available Tools

1. add_expense

Add a new expense entry to the database.

Parameters:

• date (string, required): Date in YYYY-MM-DD format
• amount (float, required): Expense amount
• category (string, required): Expense category
• subcategory (string, optional): Sub-category for more detailed tracking
• note (string, optional): Additional notes about the expense

Example:

add_expense(
    date="2025-10-06",
    amount=50.00,
    category="Food",
    subcategory="Groceries",
    note="Weekly shopping"
)

2. list_expenses

List all expenses within a date range.

Parameters:

• start_date (string, required): Start date in YYYY-MM-DD format
• end_date (string, required): End date in YYYY-MM-DD format

Example:

list_expenses(start_date="2025-10-01", end_date="2025-10-31")

3. summarize

Get a summary of expenses grouped by category.

Parameters:

• start_date (string, required): Start date in YYYY-MM-DD format
• end_date (string, required): End date in YYYY-MM-DD format
• category (string, optional): Filter by specific category

Example:

summarize(start_date="2025-10-01", end_date="2025-10-31")

Database Schema

The application uses a single SQLite table:

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
)

Configuration

The database file expenses.db is created automatically in the project directory on first run.

MCP Integration

To use this server with Claude or other MCP clients, add it to your MCP configuration:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "python",
      "args": ["path/to/expense-tracker-mcp-server/main.py"]
    }
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Author

Created with ❤️ for better expense tracking

Acknowledgments

• Built with FastMCP
• Uses SQLite for data persistence