SpendWise MCP 📊

SpendWise is a secure, multi-tenant expense-tracking server exposed through the Model Context Protocol (MCP). It allows AI agents (like Claude, Grok, or Cursor) to manage personal finances, analyze spending habits, enforce budgets, and send real-time Telegram alerts.

Built with a focus on production-grade security, strict data validation, and multi-tenant data isolation.

✨ Key Features

🧾 Core Expense Management

• Full CRUD: Create, read, update, and soft-delete expenses.

• Idempotency & Safety: Prevents accidental duplicate entries and safely handles network retries using idempotency keys.

• Multi-Currency Support: Tracks expenses in any 3-letter currency code (INR, USD, EUR, etc.) without mixing them.

📈 Financial Analytics

• Spending Summaries: Aggregate active spending by category, month, or merchant over custom date ranges.

• Period Comparison: Compare spending across two date ranges with absolute and percentage changes.

💰 Budget Management & Alerts

• Dynamic Budgets: Set weekly or monthly spending limits per category (upsert logic).

• Status Tracking: Automatically calculates budget health (🟢 Healthy, 🟡 Warning at 80%, 🔴 Over Budget at 100%).

• Telegram Alerts: Sends real-time notifications via the CallMeBot API when budgets are at risk.

🔐 Multi-Tenant Security

• Strict Isolation: Every expense and budget is scoped to the authenticated user.

• Dual Auth: Supports Auth0 RS256 JWTs for production and legacy API keys for local testing.

• Server-Side Identity: User identity is derived strictly from verified JWT claims, preventing client-side spoofing.

Related MCP server: Personal Expense Tracker MCP

🛠 Tech Stack

• Core: Python 3.12, MCP SDK (Streamable HTTP), Starlette, Uvicorn

• Database: SQLAlchemy 2.0, Alembic (Migrations), SQLite (Local), PostgreSQL (Production)

• Validation: Pydantic V2 (Strict schemas, custom validators)

• Auth: Auth0 (OAuth2 / JWT RS256)

• Notifications: CallMeBot (Telegram API), httpx

• Testing & CI: Pytest, Ruff (Lint/Format), GitHub Actions

🚀 Quick Start

Requirements

• Python 3.12+

• uv (Python package manager)

Local Setup

1. Install dependencies:

   uv sync

PROJECT STRUCTURE

spendwise-mcp/ ├── .github/workflows/ # CI/CD pipeline (lint, test, migration checks) ├── alembic/versions/ # Database schema migrations ├── src/spendwise/ │ ├── app.py # Starlette ASGI app & Auth middleware │ ├── auth.py # Auth0 JWT & API key verification │ ├── db.py # SQLAlchemy engine & session management │ ├── models.py # Expense & Budget ORM models │ ├── notifications.py # CallMeBot Telegram client │ ├── schemas.py # Pydantic V2 validation schemas │ └── server.py # MCP server & 14 tool definitions ├── tests/ # 66 isolated Pytest cases ├── render.yaml # Infrastructure as Code for Render └── pyproject.toml # Project metadata & dependencies