prince210k/Personal-Finance-Management-MCP-server

Expense Tracker MCP Server

A comprehensive personal expense tracking server built with FastMCP and SQLite, designed to help you manage and analyze your personal finances efficiently.

🌟 Features

• Expense Management: Add, list, and delete expenses with detailed categorization
• Category System: Comprehensive category and subcategory system for better organization
• Date Range Filtering: Filter expenses by date ranges for focused analysis
• Expense Summarization: Get spending summaries by category and time period
• SQLite Database: Reliable local storage with automatic database initialization
• FastMCP Integration: Easy integration with Claude Desktop and other MCP-compatible clients
• RESTful API: Clean API design following REST principles

📋 Categories

The system comes with pre-configured categories including:

• Food: Groceries, dining out, delivery fees, etc.
• Transport: Fuel, public transport, parking, etc.
• Housing: Rent, maintenance, utilities, etc.
• Health: Medicines, consultations, fitness, etc.
• Entertainment: Movies, streaming, games, etc.
• Shopping: Clothing, electronics, home decor, etc.
• And many more...

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• pip or uv package manager

Installation

1. Clone the repository:

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

2. Install dependencies:

   # Using pip
   pip install -r requirements.txt
   
   # Using uv (recommended)
   uv pip install -r requirements.txt
   

3. Run the server:

   # Development mode (with inspector)
   uv run fastmcp dev main.py
   
   # Production mode
   uv run fastmcp run main.py
   

Integration with Claude Desktop

To integrate with Claude Desktop:

uv run fastmcp install claude-desktop main.py

This will automatically configure Claude Desktop to use your expense tracker.

📊 Available Tools

🏗️ Project Structure

expense-tracker/
├── src/
│   └── expense_tracker/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # Main FastMCP server
│       ├── database.py          # SQLite database operations
│       └── categories.py        # Category management
├── data/
│   ├── categories.json          # Category definitions
│   └── expenses.db              # SQLite database (created automatically)
├── examples/
│   └── usage_examples.md        # Usage examples and configurations
├── main.py                      # Entry point
├── MCP_SERVER_CONFIG.md         # MCP server configuration guide
├── pyproject.toml              # Project configuration
├── requirements.txt            # Dependencies
├── uv.lock                     # uv package manager lock file
├── CHANGELOG.md                # Version history
├── LICENSE                     # MIT License
├── .gitignore                  # Git ignore rules
└── README.md                   # This file

⚙️ Configuration

Custom Database Location

from expense_tracker.database import ExpenseDatabase

# Use custom database path
db = ExpenseDatabase(db_path="/path/to/your/expenses.db")

Custom Categories

You can modify the data/categories.json file to add your own categories and subcategories:

{
  "custom_category": [
    "subcategory1",
    "subcategory2",
    "other"
  ]
}

📝 API Reference

ExpenseDatabase Class

The core database class that handles all SQLite operations.

Methods

• add_expense(date, amount, category, subcategory='', note='') - Add new expense
• list_expenses(start_date=None, end_date=None) - List expenses with optional filtering
• delete_expense(expense_id) - Delete expense by ID
• summarize(start_date, end_date, category=None) - Generate spending summaries
• delete_all(start_date=None, end_date=None) - Bulk delete expenses

CategoryManager Class

Manages expense categories and subcategories.

Methods

• get_categories() - Get categories as JSON string

🐛 Bug Reports

Found a bug? Please open an issue with:

• Python version
• FastMCP version
• Steps to reproduce
• Expected vs actual behavior
• Any error messages

💡 Feature Requests

Have an idea for improvement? Open an issue with:

• Clear description of the feature
• Use case explanation
• Potential implementation approach

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• FastMCP for the excellent MCP framework
• SQLite for reliable database storage
• The MCP community for inspiration and support

Made with ❤️ by [Your Name]