Expense Tracker MCP Server

A Model Context Protocol (MCP) server for comprehensive expense and income tracking with SQLite persistence. Enables AI assistants like Claude to manage your personal finances through natural conversation.

Overview

This MCP server provides a complete financial tracking system that allows you to:

• Track expenses with categories, subcategories, and notes
• Record income from multiple sources
• Analyze spending patterns and calculate net balance
• Edit and delete historical entries
• Generate financial summaries by category and date range

The server uses SQLite for reliable data persistence and exposes all functionality through MCP tools that can be called by compatible AI assistants.

Features

Expense Management

• Add expenses with date, amount, category, optional subcategory and notes
• Edit existing expenses - update any field(s) selectively
• Delete expenses by ID
• List expenses within any date range
• Categorize spending across 10+ predefined categories (Food, Transportation, Healthcare, etc.)

Income Tracking

• Record income from salary, bonuses, refunds, and other sources
• Edit income entries with flexible field updates
• Delete income records as needed
• View income history by date range

Financial Analysis

• Calculate net balance (income - expenses) for any period
• Summarize expenses by category with totals and transaction counts
• Filter summaries by specific categories
• Time-based reporting with customizable date ranges

Installation

Prerequisites

• Python 3.8+
• FastMCP library

Setup

1. Clone the repository

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

2. Install dependencies

pip install fastmcp aiosqlite

3. Run the server

For HTTP transport (FastMCP Cloud):

python main.py

For stdio transport (Claude Desktop): Edit main.py to use:

mcp.run()  # instead of mcp.run(transport="http", ...)

Usage Examples

Once connected to an AI assistant with this MCP server enabled:

Track an expense:

"Add a $45 grocery expense for today in Food & Dining category"

Record income:

"Log my $5000 salary payment from January 15th"

Check your balance:

"What's my net balance for December 2024?"

Analyze spending:

"Show me a breakdown of my expenses by category this month"

Edit a transaction:

"Change expense ID 5 to $50 instead of $45"

View history:

"List all my transportation expenses from last week"

Database Schema

Expenses Table

id          INTEGER PRIMARY KEY
date        TEXT (YYYY-MM-DD format)
amount      REAL
category    TEXT
subcategory TEXT
note        TEXT

Income Table

id      INTEGER PRIMARY KEY
date    TEXT (YYYY-MM-DD format)
amount  REAL
source  TEXT
note    TEXT

API Tools

Expense Tools

• add_expense(date, amount, category, subcategory?, note?)
• edit_expense(expense_id, date?, amount?, category?, subcategory?, note?)
• delete_expense(expense_id)
• list_expenses(start_date, end_date)

Income Tools

• add_income(date, amount, source, note?)
• edit_income(income_id, date?, amount?, source?, note?)
• delete_income(income_id)
• list_income(start_date, end_date)

Analysis Tools

• get_balance(start_date, end_date) - Returns total income, expenses, and net balance
• summarize(start_date, end_date, category?) - Groups expenses by category with totals

Configuration

Database Location: The SQLite database is created in your system's temp directory (/tmp/expenses.db on Unix-like systems). This ensures write permissions work across different environments.

Categories: Default expense categories are defined in the code. You can customize them by creating a categories.json file in the project directory.

Deployment

This server is designed to work with:

• FastMCP Cloud - Hosted MCP server accessible via HTTP
• Claude Desktop - Local MCP server using stdio transport
• Any MCP-compatible client

For FastMCP Cloud deployment, the server runs on 0.0.0.0:8000 by default.

Technical Details

• Framework: FastMCP (MCP server implementation)
• Database: SQLite with WAL mode for better concurrency
• Async: Full async/await support with aiosqlite
• Error Handling: Comprehensive error messages for debugging
• Data Validation: Existence checks before updates/deletes

License

MIT License - feel free to use and modify for your needs.

Contributing

Contributions welcome! Feel free to open issues or submit pull requests for:

• Additional financial analysis features
• New expense categories
• Budget tracking capabilities
• Data export functionality
• Recurring transaction support

---

Note: This server stores financial data locally. Always maintain backups of your expenses.db file and use secure practices when deploying publicly accessible instances.