expense-tracker-mcp-server

Lnxtanx/expense-tracker-mcp-server

3.2

If you are the rightful owner of expense-tracker-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Expense Local-MCP Tracker is a lightweight, efficient expense management system built using the Model Context Protocol (MCP) server architecture, leveraging FastMCP and SQLite for local data management.

Tools
2
Resources
0
Prompts
0

💰 Expense Local-MCP Tracker

Created by: Vivek

A powerful, lightweight expense tracking system built as a Model Context Protocol (MCP) server using FastMCP and SQLite. This project demonstrates modern Python development practices for creating efficient local data management tools.

🏗️ Project Overview

The Expense Local-MCP Tracker is a sophisticated yet simple expense management system that leverages the Model Context Protocol to provide seamless integration with AI assistants and other MCP-compatible clients. Built with Python and SQLite, it offers a robust foundation for personal finance tracking without the complexity of external dependencies.

🎯 Key Features

  • 🔧 MCP Server Architecture: Built on FastMCP framework for seamless AI integration
  • 💾 Local SQLite Database: Secure, file-based storage with no external dependencies
  • 📊 Expense Management: Add, view, and organize expenses with categories and subcategories
  • 🏷️ Flexible Categorization: Support for main categories and detailed subcategories
  • � Notes Support: Add detailed descriptions to each expense entry
  • ⚡ Fast Performance: Optimized database queries with indexed operations
  • 🔒 Data Privacy: All data stored locally on your machine

🛠️ Technology Stack

Core Technologies

  • Python 3.10+: Modern Python with type hints and performance optimizations
  • FastMCP: Lightweight MCP server framework for AI integration
  • SQLite3: Embedded relational database for local data storage
  • UV Package Manager: Fast, reliable Python package management

Development Tools

  • Git: Version control with comprehensive .gitignore
  • Virtual Environment: Isolated Python environment using .venv
  • Project Configuration: Modern pyproject.toml setup

📁 Project Structure

expenses/
├── 📄 main.py              # Main MCP server implementation
├── 🧪 test.py              # Test suite (duplicate of main for testing)
├── 📊 expenses.db          # SQLite database file (auto-generated)
├── ⚙️ pyproject.toml       # Project configuration and dependencies
├── 📚 README.md            # This comprehensive documentation
├── 🔒 .gitignore           # Git ignore patterns
├── 🐍 .python-version      # Python version specification (3.10)
├── 🔐 uv.lock              # Dependency lock file
├── 📁 .venv/               # Virtual environment directory
├── 📁 .git/                # Git repository metadata
└── 📁 __pycache__/         # Python bytecode cache

🗄️ Database Schema

Expenses Table

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Unique identifier
    date TEXT NOT NULL,                     -- Expense date (YYYY-MM-DD format)
    amount REAL NOT NULL,                   -- Expense amount (decimal)
    category TEXT NOT NULL,                 -- Main category (e.g., "Food", "Transport")
    subcategory TEXT DEFAULT '',            -- Detailed subcategory (e.g., "Restaurant", "Gas")
    note TEXT DEFAULT ''                    -- Additional notes or description
);

Database Features

  • Auto-incrementing ID: Unique identifier for each expense
  • Date Storage: Text-based date storage for flexibility
  • Decimal Precision: Real number storage for accurate monetary values
  • Optional Fields: Subcategory and notes with default empty values
  • Indexed Queries: Optimized for date-based sorting and retrieval

🚀 Installation & Setup

Prerequisites

  • Python 3.10 or higher
  • UV package manager (recommended) or pip

Quick Start

# Clone the repository
git clone https://github.com/Lnxtanx/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# Create and activate virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# Install dependencies
uv sync
# or with pip
pip install fastmcp

# Run the MCP server
python main.py

Database Initialization

The SQLite database is automatically created when the server first runs. No manual setup required!

🔧 MCP Tools & API

Available Tools

1. add_expense

Purpose: Add a new expense entry to the database

Parameters:

  • date (required): Expense date in YYYY-MM-DD format
  • amount (required): Expense amount as decimal number
  • category (required): Main expense category
  • subcategory (optional): Detailed subcategory
  • note (optional): Additional description

Returns: JSON object with status and new expense ID

Example Usage:

add_expense(
    date="2025-10-09",
    amount=15.50,
    category="Food",
    subcategory="Lunch",
    note="Team lunch at downtown restaurant"
)
2. list_expenses

Purpose: Retrieve all expenses ordered by date (newest first)

Parameters: None

Returns: Array of expense objects with all fields

Example Response:

[
    {
        "id": 1,
        "date": "2025-10-09",
        "amount": 15.50,
        "category": "Food",
        "subcategory": "Lunch",
        "note": "Team lunch at downtown restaurant"
    }
]

💡 Usage Examples

Category Suggestions

  • Food: Restaurant, Groceries, Snacks, Coffee
  • Transport: Gas, Public Transit, Taxi, Parking
  • Entertainment: Movies, Games, Books, Subscriptions
  • Utilities: Electricity, Water, Internet, Phone
  • Healthcare: Doctor, Pharmacy, Insurance, Dental
  • Shopping: Clothing, Electronics, Home, Personal Care

Integration with AI Assistants

This MCP server can be integrated with AI assistants that support the Model Context Protocol, allowing for natural language expense tracking:

"Add a $12.50 expense for coffee this morning"
"Show me all my food expenses this month"
"Record $45 for gas yesterday"

🧪 Testing

The project includes a test file (test.py) that mirrors the main implementation for testing purposes:

# Run tests
python test.py

🔒 Security & Privacy

  • Local Storage: All data remains on your local machine
  • No Network Dependencies: Operates entirely offline
  • SQLite Security: Database files can be encrypted if needed
  • Version Control: Sensitive data excluded via .gitignore

🚀 Future Enhancements

Planned Features

  • Date range filtering for expenses
  • Category-based expense summaries
  • Monthly/yearly expense reports
  • Budget tracking and alerts
  • Data export capabilities (CSV, JSON)
  • Expense editing and deletion tools
  • Advanced search and filtering
  • Data visualization integration

Potential Integrations

  • Bank account synchronization
  • Receipt image processing
  • Multi-currency support
  • Cloud backup options
  • Mobile companion app

🤝 Contributing

This project welcomes contributions! Areas for improvement:

  • Additional MCP tools and functionality
  • Enhanced database operations
  • Performance optimizations
  • Documentation improvements
  • Test coverage expansion

How to Contribute

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

� Development Notes

Code Quality

  • Clean, readable Python code with proper error handling
  • SQLite best practices with parameterized queries
  • FastMCP framework integration
  • Consistent code formatting and structure

Performance Considerations

  • Efficient database queries with proper indexing
  • Minimal memory footprint
  • Fast startup times
  • Optimized for frequent read/write operations

📄 License

This project is created by Vivek for personal and educational use. Feel free to modify and extend according to your needs.

📞 Contact

Vivek - Creator and Maintainer

Project Link: https://github.com/Lnxtanx/expense-tracker-mcp-server

🆘 Support

For issues, questions, or contributions:

  1. Check the database file permissions
  2. Verify Python version compatibility (3.10+)
  3. Ensure virtual environment is activated
  4. Review error logs for SQLite-related issues

Created with ❤️ by Vivek | Efficient expense tracking through modern Python development