Expense_Tracker_MCP

graph TD
    %% Styling Definitions
    classDef client fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef mcp fill:#0f172a,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef service fill:#1e1b4b,stroke:#c084fc,stroke-width:2px,color:#f8fafc;
    classDef repo fill:#111827,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef db fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;

    subgraph LLM_Clients[" Client Integration Layer "]
        Claude[" 🤖 Claude Desktop Client "]:::client
        Cursor[" 💻 Cursor IDE / VS Code "]:::client
        Gemini[" 🚀 Gemini CLI / Custom Agent "]:::client
    end

    subgraph MCP_Server[" Model Context Protocol (FastMCP) "]
        ToolRegistry[" ⚡ Tools Layer (17 Endpoint Handlers) "]:::mcp
        Schemas[" 🛡️ Pydantic v2 Schema Validation "]:::mcp
    end

    subgraph Application_Core[" Business & Persistence Layer "]
        Services[" ⚙️ Service Layer (Business Logic & Audit Logs) "]:::service
        Repos[" 📦 Repository Layer (Async Queries & Data Access) "]:::repo
    end

    subgraph Database_Layer[" Storage Engine "]
        PostgreSQL[(" 🐘 PostgreSQL 16 DB\n(SQLAlchemy 2.0 Async + JSONB Audits) ")]:::db
    end

    Claude -->|stdio / JSON-RPC| ToolRegistry
    Cursor -->|stdio / JSON-RPC| ToolRegistry
    Gemini -->|stdio / JSON-RPC| ToolRegistry

    ToolRegistry --> Schemas
    Schemas --> Services
    Services --> Repos
    Repos --> PostgreSQL

sequenceDiagram
    autonumber
    actor User as 👤 User
    participant Claude as 🤖 Claude Desktop
    participant MCP as ⚡ MCP Server (FastMCP)
    participant Service as ⚙️ Service / Repo
    participant DB as 🐘 PostgreSQL DB

    User->>Claude: "Add ₹450 spent on Pizza yesterday under Food"
    Claude->>Claude: Parse Intent & Select Tool `add_expense`
    Claude->>MCP: Call `add_expense(amount=450, category="Food", title="Pizza", date="2026-07-23")`
    MCP->>MCP: Validate Input Schema via Pydantic v2
    MCP->>Service: Dispatch to `ExpenseService.create()`
    Service->>DB: Execute Async INSERT & Update Budget Totals
    DB-->>Service: Return Transaction Record + Audit ID
    Service-->>MCP: Format Structured Response
    MCP-->>Claude: JSON Tool Result (Success Payload)
    Claude-->>User: "Expense of ₹450 logged successfully! Monthly Food budget remaining: ₹3,550."

Expense_Tracker_MCP/
├── 📁 expense_tracker/            # Main Application Package
│   ├── 📁 database/               # Database Connection & Migration Setup
│   │   ├── 📁 models/             # SQLAlchemy 2.0 ORM Models (Expense, Budget, CreditCard, Audit)
│   │   ├── 📄 connection.py       # Async Engine & Session Generators
│   │   └── 📄 base.py             # Declarative Base & Mixins
│   ├── 📁 repositories/           # Data Access Layer (Decoupled SQLAlchemy Queries)
│   │   ├── 📄 expense_repo.py
│   │   ├── 📄 budget_repo.py
│   │   └── 📄 card_repo.py
│   ├── 📁 services/               # Core Business Logic & Audit Trail Handlers
│   │   ├── 📄 expense_service.py
│   │   ├── 📄 budget_service.py
│   │   └── 📄 report_service.py
│   ├── 📁 schemas/                # Pydantic v2 Request/Response Validation Models
│   │   └── 📄 financial_schemas.py
│   ├── 📁 tools/                  # FastMCP Endpoint Registration Handlers (17 Tools)
│   │   ├── 📄 expense_tools.py
│   │   ├── 📄 budget_tools.py
│   │   ├── 📄 card_tools.py
│   │   └── 📄 report_tools.py
│   └── 📄 server.py               # FastMCP Server Entrypoint & Initialization
├── 📁 alembic/                    # Database Schema Migration Scripts
│   ├── 📁 versions/               # Sequential Version Stamps
│   └── 📄 env.py                  # Migration Environment Config
├── 📁 tests/                      # Pytest Test Suite (SQLite In-Memory / Asyncpg)
│   ├── 📄 test_expenses.py
│   ├── 📄 test_budgets.py
│   └── 📄 test_reports.py
├── 📄 docker-compose.yml          # Production PostgreSQL & MCP Stack Containerization
├── 📄 Dockerfile                  # Multi-stage Lightweight Python 3.12 Build
├── 📄 pyproject.toml              # UV / Hatchling Project Configuration
├── 📄 alembic.ini                 # Alembic Configuration Settings
└── 📄 README.md                   # Project Documentation

git clone https://github.com/satyam0singh/Expense_Tracker_MCP.git
cd Expense_Tracker_MCP

# Create virtual environment with uv
uv venv

# Activate Virtual Environment
# On Linux/macOS:
source .venv/bin/activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install package dependencies in editable mode
uv pip install -e .

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/expense_db
USER_ID=123e4567-e89b-12d3-a456-426614174000
ENVIRONMENT=production
LOG_LEVEL=INFO

uv run alembic upgrade head

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/Expense_Tracker_MCP",
        "run",
        "python",
        "-m",
        "expense_tracker.server"
      ],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://postgres:postgres@localhost:5432/expense_db",
        "USER_ID": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }
}

+-----------------------------------------------------------------------------------+
|                            CLAUDE DESKTOP DEMO PLACEHOLDER                        |
|                                                                                   |
|  User: "Add ₹450 spent on Pizza yesterday."                                        |
|  Claude: [Executing Tool: add_expense]                                            |
|          -> Amount: ₹450.00 | Category: Food | Date: 2026-07-23                       |
|          "Successfully recorded expense #104. Remaining Food Budget: ₹3,550.00"   |
+-----------------------------------------------------------------------------------+

💬 User
"Add ₹450 spent on Pizza yesterday."

🤖 Claude (via Expense Tracker MCP)
Calling tool: add_expense(amount=450, category="Food & Dining", title="Pizza", date="2026-07-23")

Response:
✅ Expense recorded successfully!
• Transaction ID: #104
• Amount: ₹450.00
• Category: Food & Dining
• Date: July 23, 2026

📊 Budget Update:
You have spent ₹6,450 of your ₹10,000 Food budget for July. (64.5% consumed, ₹3,550 remaining).

💬 User
"How much did I spend on Food this month? Show me a breakdown."

🤖 Claude (via Expense Tracker MCP)
Calling tool: get_category_breakdown(month=7, year=2026)

Response:
Here is your Food spending summary for July 2026:

 Total Spent: ₹6,450.00 (14 transactions)

Breakdown:
 🛒 Groceries:     ₹3,800.00 (58.9%)
 🍕 Dining Out:    ₹2,150.00 (33.3%)
 ☕ Coffee Shops:  ₹500.00   (7.8%)

💡 Insight: Your dining out expenses increased by 12% compared to June.

uv run pytest tests