Xpenser - oprn-source personal AI-enabled finance tracker

MCP金融服务

提供方 cleverbrush

金融服务 未标注 OAuth 授权 社区 / 第三方 CursorCodexZed

xpenser.cleverbrush.com is a ln open-source, self-hostable personal expense and income tracking app supporting different currencies, categories, vendors, automated invoice parsing, AI geberated reports and more.

一句话选型结论

按资料字段整理

Xpenser - oprn-source personal AI-enabled finance tracker 属于金融服务类 MCP 服务器,传输方式未标注,OAuth 授权,可直接接入 Cursor、Codex、Zed,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类金融服务 传输方式未标注 鉴权OAuth 授权 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

金融服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

personal finance expense tracking budgeting mcp server model context protocol open source self hosted

支持客户端

适用场景

personal financeexpense trackingbudgeting

安装与配置

未标注 OAuth 授权
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
行情与财务数据

查行情、财报、汇率等金融数据。

支付与账务查询

查订单、账单与交易流水。

风控与核验

做身份、信用与风险信息核验。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 已适配 Cursor、Codex、Zed,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在金融服务场景里让模型直接调用外部能力的人。
  • 已经在用 Cursor、Codex 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Xpenser - oprn-source personal AI-enabled finance tracker当前 未标注 未标注 未标注 无 未标注
Alpaca MCP 62 stdio · 本地进程 支持远程部署 有 2026-05-18
OpenNews MCP 11 stdio · 本地进程 支持远程部署 有 2026-05-17
MCP Server 273df76d 未标注 stdio · 本地进程 本地部署 有 2026-05-17
tradingview-mcp 未标注 stdio · 本地进程 本地部署 有 2026-04-19
goat (Goat SDK) 未标注 未标注 未标注 无 2026-05-17

服务器档案

金融服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方cleverbrush上游标注的维护方 cleverbrush
分类金融服务本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Cross-platform本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

13.0 KB
来自项目仓库与上游目录的原文,未做删改

xpenser

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, 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.

Why xpenser

  • 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.
  • 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.

Screenshots

Dashboard month view
Transaction history
Email reports, API keys, and MCP

Built With Cleverbrush

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 if
you are here to learn the framework patterns behind the app. For upstream
framework docs, use:

  • Cleverbrush Framework source
  • Cleverbrush Framework docs
  • Cleverbrush Schema docs

Quick Start

Prerequisites

  • Node.js 24
  • npm 11
  • Docker with Docker Compose v2 (docker compose)

1. Install dependencies```sh

npm install


### 2. Create a local environment file```sh
cp .env.example .env

The defaults in .env.example are safe for local development and point the app
at PostgreSQL on localhost:5432.

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

3. Build shared workspaces

The apps import local packages from their built dist outputs, so build the
shared packages once before starting dev servers:```sh
npm run build -w @xpenser/contracts
npm run build -w @xpenser/client
npm run build -w @xpenser/ui


### 4. Start PostgreSQL```sh
docker compose up -d postgres

Useful checks:```sh
docker compose ps postgres
docker compose logs postgres


### 5. Start the app```sh
npm run dev

The API runs database migrations on startup.

Local URLs:

  • Web app: http://localhost:3000
  • API: http://localhost:4000
  • API health check: http://localhost:4000/health
  • OpenAPI JSON: http://localhost:4000/openapi.json

Authentication

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:```env
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.

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`:```env
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.

Direct Google OAuth

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}/authjs/callback/google

For local development with the default APP_URL, use:```text
http://localhost:3000/authjs/callback/google


Configure the web app with Auth.js-standard Google variables:```env
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.

Cleverbrush Passport

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:```env
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
`/.well-known/public-key` and caches it in memory. If set,
use the base64-encoded PEM public key.

## Full Docker Run

For a production-like local run, build and start the full Compose stack:```sh
docker compose up --build

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

Full Docker URLs:

  • Web app: http://localhost:3000
  • Public API proxy: http://localhost:3000/api
  • App Swagger UI: http://localhost:3000/api-docs/swagger
  • Compose Swagger UI container: http://localhost:8090
  • SigNoz: http://localhost:8080

For public deployments, put your reverse proxy in front of the web app and set
APP_URL to 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, use docker-compose.prod.yml as the starting
point and provide production secrets for JWT_SECRET, WEB_API_SERVICE_SECRET,
and TELEGRAM_BOT_SERVICE_SECRET. Normal account-auth deployments also need
NEXTAUTH_SECRET and AUTH_SECRET; single-user deployments can leave those
empty.

Optional Integrations

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

  • OpenAI email insights: set OPENAI_API_KEY, OPENAI_REPORT_MODEL,
    RESEND_API_KEY, EMAIL_FROM, EMAIL_REPORTS_ENABLED=1, and
    EMAIL_REPORTS_SCHEDULER_ENABLED=1.
  • Telegram bot workflows: set TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME,
    and TELEGRAM_BOT_SERVICE_SECRET.
  • Vendor enrichment: set BRANDFETCH_API_KEY or BRANDFETCH_CLIENT_ID, then
    enable VENDOR_ENRICHMENT_ENABLED=1.
  • Google sign-in: configure direct Google OAuth as described above, or leave
    it disabled and use email/password accounts.
  • In-app feedback: set FEEDBACK_WEBHOOK_URL to an HTTP or HTTPS n8n webhook.
    The authenticated top-menu form stays hidden when this value is empty, which
    keeps the integration optional for self-hosted deployments.

Public API

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:```sh
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"}'
``````ts
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()
}
});


Omit `effect` or set it to `normal` for regular transactions. Use
`effect: '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_KEY` is also accepted.

## MCP Server

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:```json
{
  "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.

Development Commands```sh

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


Database helpers:```sh
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:validate is read-only and checks the live database schema against the
Cleverbrush ORM entities.

The e2e suite requires PLAYWRIGHT_BASE_URL when run outside the GitHub PR
environment.

Typed-query integration tests require a dedicated PostgreSQL database named
xpenser_queries (never point them at application data):```sh
docker run --name xpenser-query-tests -d -p 127.0.0.1:55437:5432 \
-e POSTGRES_DB=xpenser_queries -e POSTGRES_USER=xpenser_test \
-e POSTGRES_PASSWORD=xpenser_test postgres:16-alpine

Wait until PostgreSQL is ready before running the suite.

docker exec xpenser-query-tests pg_isready -U xpenser_test -d xpenser_queries
QUERY_TEST_DATABASE_URL=postgres://xpenser_test:xpenser_test@127.0.0.1:55437/xpenser_queries \
npm run test:queries:integration
docker stop xpenser-query-tests
```

The suite type-checks its fixtures, runs application migrations in a random
schema, and drops only that schema afterward. It covers joined projections,
aggregate decoding, authorization, numbered paging, filters, scan summaries,
eager ordering, and bounded enrichment query counts. It also compares query
plans on synthetic data; timings are diagnostic, not production benchmarks.
The same suite runs in the PR's Lint and test check.

It also verifies PostgreSQL-backed receipt jobs and recurring report schedules,
including worker recovery, retry limits, atomic scan results, and progress
authorization. See Background jobs for lifecycle,
retention, delivery guarantees, and deployment guidance.

Contributing

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

  • Read CONTRIBUTING.md before opening a PR.
  • Use issues for actionable bugs and feature requests.
  • Use GitHub Discussions for questions, ideas, and Cleverbrush learning threads.
  • Keep Cleverbrush contract, endpoint metadata, and handler trees aligned when
    changing the API.

Project Status

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.

License

xpenser is released under the MIT License.

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Xpenser - oprn-source personal AI-enabled finance tracker 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Xpenser - oprn-source personal AI-enabled finance tracker 怎么在 Cursor、Codex、Zed 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Xpenser - oprn-source personal AI-enabled finance tracker 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Xpenser - oprn-source personal AI-enabled finance tracker 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Xpenser - oprn-source personal AI-enabled finance tracker 支持哪些客户端?

资料标注支持 Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Xpenser - oprn-source personal AI-enabled finance tracker 能提供哪些能力?

资料显示能力标签包括 personal finance、expense tracking、budgeting、mcp server、model context protocol、open source。具体工具清单以官方文档为准。

Xpenser - oprn-source personal AI-enabled finance tracker 需要什么运行环境?

运行时为 Cross-platform。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。