Xpenser, an open-source personal finance tracker that dropped on Hacker News this week, is making the case that you don't have to hand your spending data to a third-party SaaS just to see where your money goes. The project emerged from what its creator calls a 'personal Telegram bot plus Google Sheets workflow' and has evolved into a self-hostable app with dashboards, categories, vendors, reports, multi-currency support, andβ€”most interestingly for this crowdβ€”native MCP (Model Context Protocol) access for AI agents.

Why MCP Access Is the Real Story

The MCP endpoint at /external-api/mcp lets AI agents read and manage your transactions, categories, vendors, dashboard summaries, and statistics using the same API key you'd generate from Settings. This is exactly the kind of tight integration that the AI agent ecosystem needs more of: finance data isn't just another document to summarize, it's a live operational system that agents should be able to query and manipulate. Xpenser exposes this cleanly through a typed Node client (@xpenser/client) that handles retry logic, timeouts, deduplication, batching, cache tags, and OpenTelemetry propagation under the hood.

The Cleverbrush Framework Underneath

Xpenser is also a real-world reference app for the Cleverbrush Frameworkβ€”a schema-first TypeScript stack. The packages directory shows how this works in practice: @xpenser/contracts defines public API contracts using Cleverbrush schemas, apps/api exposes those through handlers with auth metadata, OpenAPI generation, DI, logging, and tracing, while @xpenser/ui binds schema fields to reusable React form controls. It's production-shaped enough to be useful but small enough to actually inspect and learn from.

Self-Hosting Without the Pain

Deployment targets Node.js 22, npm 11, PostgreSQL via Docker Compose, with a full stack docker-compose.yml that spins up the web app, API, Swagger UI, and observability services. Local development requires building shared workspaces first (contracts, client, ui packages) before running dev servers on ports 3000 (web) and 4000 (API). The .env.example defaults are safe for local work pointing at localhost:5432. For public deployments, a reverse proxy sits in front of the Next.js web app while the API stays private on the Docker network, exposed only under /external-api.

Feature Set That Doesn't Embarrass Itself

Beyond MCP access, Xpenser handles income, expenses, refunds, and returns with categories, notes, dates, vendors, and currencies. Summaries come daily, weekly, monthly, quarterly, and yearly with category splits and trend context. Currency conversion uses the Frankfurter API automatically. Optional OpenAI-generated spending insights arrive via email on configurable schedules when you wire up OPENAI_API_KEY and RESEND_API_KEY. Vendor enrichment pulls from Brandfetch if you configure it. Telegram bot workflows are available for capture on mobile.

What's Not There Yet

The README is upfront: no bank sync, budget planning, net-worth tracking, native mobile apps, or mature import pipelines yet. User traction is currently zeroβ€”'no meaningful user traction yet,' the docs admit. But that's the tradeoff with early-stage open-source projects worth watching: you get to shape what it becomes.

Key Takeaways

  • MCP access at /external-api/mcp gives AI agents direct read/write access to your financial data
  • Schema-first TypeScript stack (Cleverbrush Framework) serves as both app and learning reference
  • Docker-based deployment with PostgreSQL, full observability stack included in docker-compose.yml
  • MIT licensed, early stage but functional enough to self-host today

The Bottom Line

Xpenser isn't going to replace YNAB or Actual Budget for most peopleβ€”yet. But for developers who want their AI agents to actually do something useful with financial data instead of just summarizing PDFs, this is one of the few projects that gives you MCP access out of the box. Keep an eye on this one.