Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.
1
Prepare the server locally
Run this once before adding it to Claude Code.
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt2
Register it in Claude Code
claude mcp add -e "SUPABASE_URL=${SUPABASE_URL}" -e "SUPABASE_KEY=${SUPABASE_KEY}" -e "GOOGLE_API_KEY=${GOOGLE_API_KEY}" expense-tracker -- python /path/to/expense-tracker-mcp/run_mcp.pyReplace any placeholder paths in the command with the real path on your machine.
Required:
SUPABASE_URLSUPABASE_KEYGOOGLE_API_KEY3
Make your agent remember this setup
expense-tracker's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Natural language expense management via Gemini AI
- Intelligent categorization using embeddings and similarity search
- Hierarchical categories for financial organization
- Real-time data synchronization
- Learning system that improves categorization accuracy over time
Tools 4
create_expenseCreate expenses from natural language inputget_spending_summaryGenerate spending summaries for a specific periodanalyze_subscriptionsAnalyze recurring subscriptions and expensesview_recent_transactionsRetrieve a list of recent financial transactionsEnvironment Variables
SUPABASE_URLrequiredURL for the Supabase database instanceSUPABASE_KEYrequiredAPI key for Supabase authenticationGOOGLE_API_KEYrequiredAPI key for accessing Gemini AI servicesTry it
→Add an expense for $15 at Starbucks for coffee.
→What is my total spending summary for this month?
→Analyze my current subscriptions and identify any I might want to cancel.
→Show me my last 5 transactions.
Original README from keyurgit45/expense-tracker-mcp
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:
- MCP Server: Core expense tracking tools exposed via Model Context Protocol
- 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 commandsPOST /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:
- Generates embeddings for transactions using Sentence Transformers
- Finds similar past transactions using pgvector
- Uses weighted voting to predict categories
- Falls back to rule-based matching
- 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