Expense Tracker MCP Server

An asynchronous Model Context Protocol (MCP) server built with Python and FastMCP to log and track personal expenses inside a local SQLite database with strict category/subcategory checks.

Features

• SQLite Database Backend: Logs expenses locally in expenses.db using aiosqlite.

• Asynchronous Execution: Fully utilizes asyncio and async database connections.

• Categorization: Validates categories and subcategories against a custom JSON hierarchy (categories.json).

• Exposed Tools:

  • add_expense: Add a new transaction (validates amount, category, and dates).

  • get_expenses: View matching logs with optional category, subcategory, start date, and end date filters.

  • get_expense_summary: View spent totals, item count, and percentages grouped by category.

  • delete_expense: Remove transaction logs by database ID.

• Exposed Resources:

  • expense://categories: Returns the JSON representation of categories and their subcategories.

  • expense://categories/{category}/subcategories: Returns subcategories for a given category in JSON format.

Files Structure

• main.py: Server entrypoint containing initialization, SQLite queries, MCP tools, and MCP resource declarations.

• categories.json: Configuration file specifying categories and subcategories.

• pyproject.toml: Package configuration with metadata and dependency requirements (fastmcp and aiosqlite).

• .gitignore: Configured to ignore virtual environments, cache directories, and local database files.

Installation

Ensure you have uv installed.

To sync dependencies:

uv sync

Running the Server

To start the MCP server locally:

uv run python main.py

Development and Testing

A test suite is available under the artifacts directory. To run the async test suite:

uv run python C:\Users\User\.gemini\antigravity-ide\brain\7f833c64-f9e4-404b-a691-0d0df923616c\scratch\test_server.py