Expense Tracker MCP Server

Expense Tracker Backend

AI-powered expense tracking system with natural language interface, intelligent categorization, and real-time sync.

Architecture

The system uses a two-server architecture:

1. MCP Server: Core expense tracking tools exposed via Model Context Protocol
2. Gemini AI Server: FastAPI server providing chat interface with authentication

Features

• 🤖 Natural language expense management via Gemini AI
• 🧠 Intelligent categorization using embeddings and similarity search
• 🔐 JWT authentication with Supabase
• 📊 Hierarchical categories for organization
• 🏷️ Predefined tag system
• 📈 Real-time data sync
• 🔄 Learning system that improves over time

Quick Start

Prerequisites

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Environment Setup

cp .env.example .env
# Add your credentials:
# - SUPABASE_URL
# - SUPABASE_KEY
# - GOOGLE_API_KEY (for Gemini)

Database Setup

Execute the SQL scripts in your Supabase SQL Editor:

# Core tables
scripts/create_tables.sql
# Embeddings support
scripts/create_embeddings_schema.sql

Run Both Servers

Terminal 1 - MCP Server:

python run_mcp.py

Terminal 2 - Gemini AI Server:

uvicorn app.servers.gemini.main:app --reload --port 8000

Initialize Data

# Populate categories
python scripts/populate_hierarchical_categories.py

# Populate predefined tags
python scripts/populate_predefined_tags.py

API Endpoints

Chat Interface

• POST /chat - Send natural language commands
• POST /auth/refresh - Refresh JWT token

MCP Tools (via chat)

• Create expenses from natural language
• Auto-categorize transactions
• Get spending summaries
• Analyze subscriptions
• View recent transactions

Flutter Client

refer https://github.com/keyurgit45/expense-tracker-client

Testing

# Run all tests with mocks
ENVIRONMENT=test pytest tests/ -v

# Run specific components
ENVIRONMENT=test pytest tests/test_mcp_tools.py -v
ENVIRONMENT=test pytest tests/test_categorization.py -v

Project Structure

backend/
├── app/
│   ├── core/              # Business logic
│   ├── servers/
│   │   ├── gemini/       # AI chat server
│   │   └── mcp/          # MCP tool server
│   └── shared/           # Shared configs
├── scripts/              # Utilities
└── tests/               # Test suite

AI Categorization

The system uses a hybrid approach:

1. Generates embeddings for transactions using Sentence Transformers
2. Finds similar past transactions using pgvector
3. Uses weighted voting to predict categories
4. Falls back to rule-based matching
5. Learns from user confirmations

Development

• API docs: http://localhost:8000/docs
• Frontend integration: Configure CORS in Gemini server
• MCP tools can be tested directly via chat interface