Show HN: Xpenser – self-hostable personal finance tracker with MCP access Xpenser, an open-source self-hostable personal finance tracker with API and MCP access, launched on Hacker News. The tool offers dashboards, categories, vendor tracking, multi-currency support, and optional AI-generated insights, serving as a reference app for the Cleverbrush Framework. xpenser is an open-source, self-hostable personal finance tracker for people who want to track and analyze income and expenses with dashboards, categories, vendors, reports, and API/MCP access. It grew out of a personal Telegram bot plus Google Sheets workflow. The project is early and still evolving, but it is useful enough to run, inspect, extend, self-host, or use as a working Cleverbrush Framework reference app. If you track or analyze expenses somewhere else today, feedback is welcome on whether xpenser could replace or complement that setup and what would need to be added. xpenser is also a real-world reference app for Cleverbrush Framework https://docs.cleverbrush.com , showing how a schema-first TypeScript stack can drive API contracts, validation, OpenAPI, typed clients, React forms, auth-aware endpoints, observability, Telegram workflows, and MCP access from one cohesive application. - Move everyday finance tracking into a structured app with dashboards, categories, vendors, reports, and searchable transaction history. - Track income, expenses, refunds, and returns with categories, notes, dates, vendors, and currencies. - Review daily, weekly, monthly, quarterly, and yearly summaries with category split and trend context. - Use multiple transaction currencies with automatic conversion to your default currency through Frankfurter https://www.frankfurter.app/ . - Capture transaction scans, enrich vendor data, and keep setup workflows usable on mobile and desktop. - Receive optional weekly and monthly email summaries with OpenAI-generated spending and income insights. - Connect external tools through API keys, a typed Node client, an MCP server, and a Telegram bot. | | xpenser is intentionally small enough to inspect while still exercising production-shaped framework patterns: packages/contracts defines the public contract with Cleverbrush schemas. apps/api exposes the contract through Cleverbrush server handlers, auth metadata, OpenAPI, DI, logging, tracing, and MCP. packages/client wraps the generated Cleverbrush client with retry, timeout, dedupe, batching, cache tags, and OpenTelemetry propagation. packages/ui binds Cleverbrush schema fields to reusable React form controls. Start with Cleverbrush Reference Notes /cleverbrush/xpenser/blob/main/docs/cleverbrush-reference.md if you are here to learn the framework patterns behind the app. For upstream framework docs, use: - Node.js 22 - npm 11 - Docker with Docker Compose v2 docker compose npm install cp .env.example .env The defaults in .env.example are safe for local development and point the app at PostgreSQL on localhost:5432 . The apps import local packages from their built dist outputs, so build the shared packages once before starting dev servers: npm run build -w @xpenser/contracts npm run build -w @xpenser/client npm run build -w @xpenser/ui docker compose up -d postgres Useful checks: docker compose ps postgres docker compose logs postgres npm run dev The API runs database migrations on startup. Local URLs: - Web app: http://localhost:3000 http://localhost:3000 - API: http://localhost:4000 http://localhost:4000 - API health check: http://localhost:4000/health http://localhost:4000/health - OpenAPI JSON: http://localhost:4000/openapi.json http://localhost:4000/openapi.json Email/password sign-in works without any external auth provider. Accounts created this way must confirm their email before signing in. Google sign-in supports two modes: - Direct Google OAuth for self-hosted deployments. - Cleverbrush Passport for the hosted Cleverbrush deployment. Select the mode with GOOGLE SIGN IN MODE : GOOGLE SIGN IN MODE=auto auto uses direct Google OAuth when AUTH GOOGLE ID and AUTH GOOGLE SECRET are configured. If those are not set, it uses Passport only when all Passport variables are configured. If neither auth provider is configured, the Google sign-in button is hidden and email/password sign-in still works. Use GOOGLE SIGN IN MODE=direct to require direct Google OAuth, GOOGLE SIGN IN MODE=passport to require Passport, or GOOGLE SIGN IN MODE=disabled to hide Google sign-in even when credentials are present. Create an OAuth 2.0 client in Google Cloud Console: - Application type: Web application - Authorized JavaScript origin: your public APP URL - Authorized redirect URI: ${APP URL}/api/auth/callback/google For local development with the default APP URL , use: http://localhost:3000/api/auth/callback/google Configure the web app with Auth.js-standard Google variables: APP URL=https://xpenser.example.com NEXTAUTH URL=https://xpenser.example.com NEXTAUTH SECRET=replace-with-at-least-32-characters AUTH SECRET=replace-with-the-same-value-as-NEXTAUTH SECRET GOOGLE SIGN IN MODE=auto AUTH GOOGLE ID=your-google-oauth-client-id AUTH GOOGLE SECRET=your-google-oauth-client-secret Google accounts must have a verified email address. If a local email/password account already exists with the same email, Google sign-in is rejected instead of silently linking the accounts. Passport is a private Cleverbrush auth broker. Self-hosted deployments should use direct Google OAuth unless they run their own compatible Passport service. Configure both services with: GOOGLE SIGN IN MODE=passport PASSPORT BASE URL=https://auth.cleverbrush.com PASSPORT PROJECT=xpenser PASSPORT ENVIRONMENT=production PASSPORT PUBLIC KEY= PASSPORT PUBLIC KEY is optional. When empty, the API fetches