💰 Expense Tracker MCP v3

A multi-user AI-powered expense tracking server built with FastMCP + FastAPI + PostgreSQL. Users can manage finances using plain English with AI.

Works with:

• 🖥 Claude Desktop

• 📱 Claude.ai Free (via N8N)

• 🌐 Any HTTP client

✨ Features

• 🔐 JWT Authentication – secure multi-user system

• 👥 Multi-user support – each user has isolated data

• 🧰 29 MCP tools for expenses, income, budgets and analytics

• 🌐 Mobile friendly registration page

• ☁ Cloud deployable (Railway + Neon)

• 🤖 AI integration with Claude

• 🔄 Claude.ai free support using N8N bridge

📁 Project Structure

expense_tracker_v3/

├── CORE
│   ├── main.py
│   ├── run.py
│   ├── app.py
│   ├── config.py
│   ├── context.py
│   ├── db.py
│   ├── init_db.py
│   ├── logger.py
│   ├── utils.py
│   └── create_user.py
│
├── DATABASE
│   ├── schema.sql
│   └── categories.json
│
├── API
│   └── api/
│       ├── __init__.py
│       ├── auth.py
│       ├── middleware.py
│       └── server.py
│
├── MCP TOOLS
│   └── tools/
│       ├── expense_tools.py
│       ├── income_tools.py
│       ├── budget_tools.py
│       ├── category_tools.py
│       ├── summary_tools.py
│       └── utility_tools.py
│
├── FRONTEND
│   └── static/
│       └── register.html
│
├── DEPLOYMENT
│   ├── Procfile
│   ├── pyproject.toml
│   └── requirements.txt
│
└── README.md

⚠ Never commit .env to GitHub.

🧰 MCP Tools (29)

Expense Tools

• add_expense

• update_expense

• delete_expense

• list_expenses

• get_expense_by_id

Related MCP server: Expense Tracker MCP Server

Income Tools

• add_income

• list_income

• delete_income

• monthly_income

Budget Tools

• set_budget

• get_budget

• check_budget_status

• delete_budget

Category Tools

• get_categories

• add_category

• update_category

• delete_category

Summary Tools

• summarize_expenses

• daily_summary

• weekly_summary

• monthly_summary

• yearly_summary

• category_breakdown

• top_spending

• compare_months

• get_balance

Utility Tools

• get_last_expenses

• search_expenses

• export_expenses_csv

🗄 Database Schema

users
 id
 username
 password
 created_at

categories
 id
 name

expenses
 id
 user_id
 date
 amount
 category_id
 note

income
 id
 user_id
 date
 amount
 source

budgets
 id
 user_id
 category_id
 monthly_limit

All queries automatically filter:

WHERE user_id = current_user

Each user has completely isolated data.

🚀 Local Setup

1️⃣ Clone Repository

git clone https://github.com/parnajaswanth227/Expense_Tracker_With_Claude.git
cd Expense_Tracker_With_Claude

2️⃣ Create Python Environment

uv init
uv venv --python 3.12
.venv\Scripts\activate

Windows users:

$env:UV_LINK_MODE="copy"

3️⃣ Install Dependencies

uv add fastmcp fastapi uvicorn psycopg[binary] python-dotenv python-jose bcrypt
uv pip install -r requirements.txt

4️⃣ Create .env

Create a .env file in the root folder.

DATABASE_URL=postgresql://user:pass@host/dbname?sslmode=require
SECRET_KEY=your_secret_key_here
ALLOW_REGISTRATION=true
ACCESS_TOKEN_EXPIRE_MINUTES=525600

Generate a secret key:

python -c "import secrets; print(secrets.token_hex(32))"

5️⃣ Start Server

uv run python run.py

Server runs at:

http://localhost:8000

🔑 API Endpoints

☁ Cloud Deployment

Step 1: Create PostgreSQL Database

Go to:

https://neon.tech

Create database and copy connection string.

Step 2: Deploy on Railway

Go to:

https://railway.app

Create project → Deploy from GitHub.

Railway will automatically use:

web: uvicorn api.server:app --host 0.0.0.0 --port $PORT

Add environment variables:

Step 3: Verify Deployment

https://your-app.railway.app/health

Expected response:

{"status":"ok"}

🖥 Using with Claude Desktop

Install MCP server:

uv run fastmcp install claude-desktop main.py

Manual configuration:

%APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
   "ExpenseTracker": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://your-app.railway.app/mcp",
       "--header",
       "Authorization: Bearer YOUR_TOKEN"
     ]
   }
 }
}

📱 Using Claude.ai Free (Mobile + Web)

Claude free plan does not support MCP connectors directly. We use an N8N workflow bridge.

N8N Architecture

Claude AI
   ↓
N8N Webhook
   ↓
Expense Tracker MCP
   ↓
PostgreSQL Database

Setup N8N

Step 1: Create Account

https://n8n.io

Create account.

Step 2: Create Workflow

Click:

New Workflow

Step 3: Import Workflow JSON

Click:

⋮ → Import from JSON

Paste provided workflow.

Step 4: Add Token

Replace:

YOUR_JWT_TOKEN_HERE

with your token.

Step 5: Activate Workflow

Click Activate.

You will receive webhook URL:

https://yourname.app.n8n.cloud/webhook/expense-tracker

Connect N8N to Claude.ai

1. Open Claude.ai

2. Go to:

Settings → Connectors

3. Select N8N

4. Paste your webhook URL.

Claude can now control your expense tracker.

Example Commands

Users can ask Claude:

Add expense ₹500 for lunch today

Show my expenses this month

Add ₹50,000 salary income

Show my balance

Check my budget

Claude will automatically call MCP tools.

👥 Multi-User Flow

User opens /register
      ↓
Creates username & password
      ↓
Receives JWT token
      ↓
Token used in
 - Claude Desktop
 - N8N workflow
 - API calls

Each user has separate database data.

🔧 Admin Create Users

python create_user.py --username alice --password pass123

Disable public signup:

ALLOW_REGISTRATION=false

🐛 Troubleshooting

🔐 Security

Never commit:

.env
JWT tokens
database credentials

Rotate tokens if exposed.

📦 Tech Stack

⭐ Project Goal

Create a fully AI-powered personal finance assistant where users manage expenses using natural language with Claude AI.

If you'd like, I can also help add:

• 🧭 Architecture diagrams

• 📸 Screenshots

• 🔄 Workflow diagrams

• 🏷 GitHub badges

• 🎬 Animated demo

to make your GitHub repository look like a professional open-source project.

📸 Screenshots

screenshorts\Screenshot 2026-03-14 113116.png

💻 Web Dashboard – Expense Summary

The AI assistant analyzes your expenses and presents a clear financial overview including income, spending distribution, and balance.

• Total income, expenses, and balance

• Category-wise spending breakdown

• Interactive spending chart

• AI-generated financial insights

Example insight:

You've spent ₹2,000 across 3 transactions. Food is the dominant category at 85% (₹1,700). With ₹60,000 income, you're saving 96.7% — a healthy balance of ₹58,000.

📱 Claude AI Mobile – Natural Language Expense Entry

C:\Users\parna\Videos\expense_tracker_v3\screenshorts\WhatsApp Image 2026-03-14 at 11.33.34 AM.jpeg Users can add expenses using natural language with AI.

Add an expense 210 rs for petrol for my bike

Claude automatically:

1. Detects the transport category

2. Calls the add_expense MCP tool

3. Stores the expense in the database

4. Returns confirmation with details

Returned response includes:

• Expense ID

• Amount

• Category

• Note

• Date

This demonstrates how users can manage finances conversationally with AI.

🌐 Live Demo

The project is deployed on Railway Cloud.

📝 User Registration Page

Create a new account:

https://web-production-d3df0.up.railway.app/register

This page allows users to:

• Create a username

• Set a password

• Generate a JWT token for authentication

🔌 MCP Server Endpoint

Main MCP endpoint used by Claude and N8N:

https://web-production-d3df0.up.railway.app/mcp

This endpoint handles:

• MCP tool execution

• AI requests from Claude

• Automation requests from N8N workflows

🧪 Health Check (Optional)

Check if the server is running:

https://web-production-d3df0.up.railway.app/health

Expected response:

{"status":"ok"}