Xpenser - oprn-source personal AI-enabled finance tracker

xpenser is intentionally small enough to inspect while still exercising production-shaped framework patterns:

- packages/contractsdefines the public contract with Cleverbrush schemas.
- apps/apiexposes the contract through Cleverbrush server handlers, auth metadata, OpenAPI, DI, logging, tracing, and MCP.
- packages/clientwraps the generated Cleverbrush client with retry, timeout, dedupe, batching, cache tags, and OpenTelemetry propagation.
- packages/uibinds Cleverbrush schema fields to reusable React form controls.

- Node.js 22
- npm 11
- Docker with Docker Compose v2 (docker compose)

The defaults in.env.exampleare safe for local development and point the app at PostgreSQL onlocalhost:5432.

SetDISABLE_GTM=1when a deployment should not load Google Tag Manager.

The apps import local packages from their builtdistoutputs, 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 ps postgres docker compose logs postgres

The API runs database migrations on startup.

Email/password sign-in works without any external auth provider. Accounts created this way must confirm their email before signing in.

Self-hosted deployments that need only one user can skip account auth entirely:

XPENSER_SINGLE_USER_MODE=1 XPENSER_SINGLE_USER_EMAIL=you@example.com WEB_API_SERVICE_SECRET=replace-with-at-least-32-characters

In single-user mode, the web app opens directly to the authenticated app, creates or reuses the configured email as the owner, hides login, registration, and marketing pages, and keeps Swagger/OpenAPI available. The public API and MCP endpoint still require API keys or OAuth; only the trusted web service bypasses the account login flow.

- Direct Google OAuth for self-hosted deployments.
- Cleverbrush Passport for the hosted Cleverbrush deployment.

Select the mode withGOOGLE_SIGN_IN_MODE:

autouses direct Google OAuth whenAUTH_GOOGLE_IDandAUTH_GOOGLE_SECRETare 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.

UseGOOGLE_SIGN_IN_MODE=directto require direct Google OAuth,GOOGLE_SIGN_IN_MODE=passportto require Passport, orGOOGLE_SIGN_IN_MODE=disabledto 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 publicAPP_URL
- Authorized redirect URI:${APP_URL}/authjs/callback/google

For local development with the defaultAPP_URL, use:

http://localhost:3000/authjs/callback/google

Configure the web app with Auth.js-standard Google variables:

APP_URL=https://xpenser.example.com AUTH_URL=https://xpenser.example.com/authjs NEXTAUTH_URL=https://xpenser.example.com/authjs 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.

GOOGLE_SIGN_IN_MODE=passport PASSPORT_BASE_URL=https://auth.cleverbrush.com PASSPORT_PROJECT=xpenser PASSPORT_ENVIRONMENT=production PASSPORT_PUBLIC_KEY=

PASSPORT_PUBLIC_KEYis optional. When empty, the API fetches<PASSPORT_BASE_URL>/.well-known/public-keyand caches it in memory. If set, use the base64-encoded PEM public key.

For a production-like local run, build and start the full Compose stack:

This starts the containerized web app, API, PostgreSQL, Swagger UI, and observability services defined indocker-compose.yml.

For public deployments, put your reverse proxy in front of the web app and setAPP_URLto the public origin. The API service stays private on the Docker network and the Next app exposes it under/api.

For a smaller public deployment, usedocker-compose.prod.ymlas the starting point and provide production secrets forJWT_SECRET,WEB_API_SERVICE_SECRET, andTELEGRAM_BOT_SERVICE_SECRET. Normal account-auth deployments also needNEXTAUTH_SECRETandAUTH_SECRET; single-user deployments can leave those empty.

The default.env.examplekeeps external integrations off unless you configure their provider credentials:

- OpenAI email insights: setOPENAI_API_KEY,OPENAI_REPORT_MODEL,RESEND_API_KEY,EMAIL_FROM,EMAIL_REPORTS_ENABLED=1, andEMAIL_REPORTS_SCHEDULER_ENABLED=1.
- Telegram bot workflows: setTELEGRAM_BOT_TOKEN,TELEGRAM_BOT_USERNAME, andTELEGRAM_BOT_SERVICE_SECRET.
- Vendor enrichment: setBRANDFETCH_API_KEYorBRANDFETCH_CLIENT_ID, then enableVENDOR_ENRICHMENT_ENABLED=1.
- Google sign-in: configure direct Google OAuth as described above, or leave it disabled and use email/password accounts.

Create an API key from Settings -> Preferences -> API keys. The API key can be used as a bearer token with curl or with the typed Node client:

curl -X POST "$APP_URL/api/transactions" \ -H "Authorization: Bearer $XPENSER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"categoryId":1,"amount":12.34,"currency":"USD","effect":"normal","occurredAt":"2026-05-13T12:00:00.000Z"}'

import { createXpenserClient } from '@xpenser/client'; const client = createXpenserClient({ baseUrl: process.env.XPENSER_API_BASE_URL ?? 'http://localhost:3000/api', getToken: () => process.env.XPENSER_API_KEY ?? null }); await client.transactions.create({ body: { categoryId: 1, amount: 12.34, currency: 'USD', effect: 'normal', occurredAt: new Date() } });

Omiteffector set it tonormalfor regular transactions. Useeffect: 'reversal'for refunds in expense categories or payments and chargebacks in income categories; the entered amount stays positive and reports subtract it from that category.

X-API-Key: $XPENSER_API_KEYis also accepted.

xpenser exposes an MCP Streamable HTTP endpoint for AI agents at/api/mcp. Use the same API key from Settings -> Preferences -> API keys as a bearer token. MCP tools can read and manage the API-key owner's vendors, categories, and transactions, so treat MCP access as full account data access. Use a dedicated API key for MCP clients and revoke it when access is no longer needed:

{ "mcpServers": { "xpenser": { "type": "streamable-http", "url": "https://xpenser.example.com/api/mcp", "headers": { "Authorization": "Bearer ${XPENSER_API_KEY}" } } } }

The MCP server exposes tools for the current user, vendors, categories, transactions, dashboard summaries, and statistics. Vendor candidate search and enrichment may call the configured vendor enrichment provider.

npm run lint npm run typecheck npm test npm run test:e2e

npm run db:run -w @xpenser/api npm run db:validate -w @xpenser/api docker compose stop postgres docker compose down docker compose down -v

db:validateis read-only and checks the live database schema against the Cleverbrush ORM entities.

The e2e suite requiresPLAYWRIGHT_BASE_URLwhen run outside the GitHub PR environment.

Contributions are welcome. Good first areas include documentation, self-hosting guides, framework reference notes, UI polish, API examples, and small focused product improvements.

xpenser is early, practical, and evolving. It has no meaningful user traction yet; feedback on product fit, README clarity, self-hosting, and MCP workflows is welcome. The goal is to remain useful as a personal finance app while staying clear enough for developers to learn how a Cleverbrush full-stack project fits together.

xpenser does not currently ship bank sync, budget planning, net-worth tracking, native mobile apps, or mature import pipelines.

Free crypto address labels. Identify known addresses on major networks with a free API.

Clean SEC EDGAR company financials, ratios, filings, and 10-K/10-Q sections as normalized JSON — a hosted MCP server with 5 tools and a free tier.

Check live market data and execute real trades — buy/sell tokens and stocks, open leveraged perp positions, trade prediction markets, move funds in and out of savings

international financial reporting engine for Agents and REST api users journal entries, statement generation, audit trail with workings, financial reporting automation

A paid MCP server for invoice processing. Three tools: extract structured data from any invoice (pasted text, URL, or PDF), validate the extracted invoice for completeness and mathematical accuracy, and classify the expense into an accounting category with a suggested nominal account code and tax deductibility flag. Priced from $0.005 to $0.01 per call, paid in USDC on Base via x402. No API key required.

English background checks on Korean (KRX) stocks from DART filings: dilution history, delisting-risk flags, every claim linked to the original filing.

Turn PDF bank statements into checked Excel, CSV or JSON with balance validation.

Real-time tweet counters and market data for Polymarket's Elon Musk & Ted Cruz markets — hosted remote MCP server (streamable-http + SSE), free tier is keyless.

Official hosted MCP adapter for Quote.Trade market data and guarded account/order workflows; no withdrawal tools.

Agentic Document Parsing and Extraction (ADP)