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](file:///d:/coding/expense-tracker-mcp-server/main.py): Server entrypoint containing initialization, SQLite queries, MCP tools, and MCP resource declarations.
• [categories.json](file:///d:/coding/expense-tracker-mcp-server/categories.json): Configuration file specifying categories and subcategories.
• [pyproject.toml](file:///d:/coding/expense-tracker-mcp-server/pyproject.toml): Package configuration with metadata and dependency requirements (fastmcp and aiosqlite).
• [.gitignore](file:///d:/coding/expense-tracker-mcp-server/.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