ExpenseTracker MCP Server

A Model Context Protocol (MCP) server for managing personal expenses. Built with FastMCP, this server provides tools for tracking, querying, and summarizing expenses through an AI-ready interface.

Overview

ExpenseTracker is a lightweight MCP server that enables Claude and other AI applications to:

• Add expenses to a SQLite database with categories and notes
• Query expenses by date range for review and analysis
• Summarize expenses by category to understand spending patterns
• Manage categories through a configurable JSON file

This project demonstrates how to build a practical MCP server that integrates with AI assistants for real-world expense management.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI applications to interact with local tools and data sources safely. MCP servers expose resources and tools that AI models can access through a standardized interface, enabling features like:

• Tool use and automation
• Resource access and management
• Server-side processing with client-side oversight

Learn more at modelcontextprotocol.io

Features

• 📊 Add Expenses - Log expenses with date, amount, category, subcategory, and notes
• 🔍 Query Expenses - Retrieve expenses within a date range with full filtering
• 💰 Summarize Spending - Get expense totals by category for budget analysis
• 📁 Category Management - Maintain a flexible list of expense categories via JSON
• 🗄️ SQLite Backend - Persistent storage with no external dependencies
• 🤖 MCP Integration - Works seamlessly with Claude and other MCP-compatible clients

Installation

Prerequisites

• Python 3.14+
• pip or uv package manager

Setup

1. Clone the repository

   git clone https://github.com/yourusername/local-mcp-server.git
   cd local-mcp-server
   

2. Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -e .
   # Or with uv:
   uv sync
   

4. Create categories file (optional)

   cat > categories.json << 'EOF'
   {
     "categories": [
       "Food & Dining",
       "Transportation",
       "Entertainment",
       "Shopping",
       "Bills & Utilities",
       "Health & Fitness",
       "Travel",
       "Other"
     ]
   }
   EOF
   

Usage

Running the Server

Start the MCP server:

python main.py

The server will initialize the SQLite database and listen for MCP connections.

Available Tools

add_expense

Add a new expense entry to the database.

Parameters:

• date (string, required): Date in YYYY-MM-DD format
• amount (number, required): Expense amount
• category (string, required): Expense category
• subcategory (string, optional): Subcategory for detailed tracking
• note (string, optional): Additional notes or description

Example:

{
  "date": "2024-06-14",
  "amount": 45.50,
  "category": "Food & Dining",
  "subcategory": "Restaurant",
  "note": "Lunch at Italian place"
}

list_expenses

Retrieve expenses within a date range.

Parameters:

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

Example:

{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30"
}

Returns: Array of expense objects with id, date, amount, category, subcategory, and note fields.

summarize

Get a summary of expenses by category within a date range.

Parameters:

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

Example:

{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30",
  "category": "Food & Dining"
}

Returns: Array of category summary objects with category and total_amount fields.

Resources

expense://categories

Access the current list of expense categories. The categories file is read fresh on each access, allowing modifications without server restart.

MIME Type: application/json

Configuration

Database

The SQLite database file is stored as expenses.db in the project root. The database is automatically initialized on first run with the expenses table.

Schema:

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 ''
)

Categories

Edit categories.json to customize the list of expense categories available for your use case. Changes are reflected immediately without restarting the server.

Project Structure

local-mcp-server/
├── main.py              # MCP server implementation
├── expenses.db          # SQLite database (auto-created)
├── categories.json      # Category definitions
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
├── LICENSE             # GPL 3.0 license
└── README.md           # This file

Technical Details

• Framework: FastMCP
• Database: SQLite3 (built-in Python library)
• Protocol: Model Context Protocol (MCP)
• Language: Python 3.14+

Integration with Claude

To use this server with Claude or other MCP clients, configure your client to connect to this server. Consult your client's documentation for MCP server setup instructions.

Development

Running Tests

Currently, no automated tests are included. Manual testing via an MCP client is recommended.

Code Style

The project follows standard Python conventions. Use of type hints and docstrings is encouraged for future contributions.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

Roadmap

Future enhancements may include:

• [ ] Budget tracking and alerts
• [ ] Recurring expenses
• [ ] Multi-user support
• [ ] Export functionality (CSV, PDF)
• [ ] Advanced analytics and reports
• [ ] Tagging system for expenses
• [ ] Receipt attachment storage

Support

For issues, questions, or suggestions, please open an issue on GitHub or contact the maintainers.

Acknowledgments

• Built with FastMCP
• Implements the Model Context Protocol
• Inspired by the need for AI-friendly expense tracking tools