moneyhelper

mcp
Security Audit
Pass
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 85 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Moneyhelper | 算清每一笔,攒稳每一步 —— 对话优先的个人理财智能体:一句话记账、持仓风控、股票投研、财报分析、策略回测、团队模拟盘。FastAPI + LangGraph + React,本地优先、数字可复核、MCP 开放。

README.md

Moneyhelper

A conversation-first personal finance assistant. One sentence to record an expense, check quotes, manage positions, run a health check, or get your morning report.

License
Release
CI
Docker
Python
FastAPI
React
LangGraph

简体中文 English
README.zh.md README.md (current)

30-second start

docker compose up -d --build     # http://localhost:8787
# Or run locally (Python 3.10+ / Node 18+): one command — venv + pip install + SPA build + serve on 8788
scripts/dev.sh --prod

Why Moneyhelper

  • Every number comes from a deterministic engine — the model only classifies intent and writes prose, so it cannot invent an amount.
  • Built for Chinese bills — WeChat Pay, Alipay and bank CSV imports are native, not an afterthought.
  • Conversation is the operation — one sentence records an expense, opens a position, or gets a rebalancing plan.
  • Your data stays on your machine — local SQLite, with optional passphrase-protected encrypted backups.

What it is

Moneyhelper is not "a generic chat model + a bookkeeping plugin" — it is a local-first vertical finance intelligence workbench:
a general-model base focused end-to-end on personal / retail / small-business finance decisions — bookkeeping,
position risk control, stock research, corporate statement analysis, strategy backtesting and team paper-trading, every conclusion
visualized and traceable.

Moneyhelper is the helper for your money: a local-first workbench that turns every entry into a decision you can check,
so saving and investing stay deliberate instead of hopeful.

What makes it different from a generic assistant

Dimension Generic LLM assistant Moneyhelper finance workbench
Core logic Text-first; fluency beats accuracy Computation-first: the model narrates, deterministic code computes
Financial accuracy Relies on memorized knowledge; formulas/tax/ratios hallucinate Metric definitions live in docstrings; insufficient data returns null with a reason — never a plausible fake number
Capability boundary Can chat about anything, finance stays "encyclopedia-level" Finance only, but runs the whole loop: bookkeeping → position risk → research → statements → backtest
Interaction Mostly plain-text chat Chat + visual workbench: ask once, get charts, tables and conclusions
Privacy Raw data goes to the model provider Local-first: sensitive data stays in local SQLite, only sanitized structured data leaves the machine
Workflow Single-turn Q&A, no persistent state Persistent finance workspace: assets, positions, statements, backtests survive across sessions
You say Moneyhelper does
"coffee 28, taxi 32" Records two entries in one sentence
"salary 1w credited" Records income 10000 (supports 万/w/k and Chinese numerals)
"check CATL, add to watchlist if good" Quote → add to watchlist → visible on Market
"buy 100 shares of 600519" Opens a position at the current price (asks for cost when quotes are unavailable)
"sell half of 600519" Half-position sell, never an accidental full liquidation
"analyze the technicals of 600519" Research tab: K-line + MA/MACD/RSI/BOLL/KDJ + signal stream + bias
"how does a MA cross-over strategy do on 600519" Research tab: backtest with return/drawdown/Sharpe/win rate + equity curve
"here are two years of statements" Statements tab: 20+ metrics, DuPont, trend charts, radar, anomaly alerts
"open paper accounts for the team, who performs best" Paper Trading tab: open account → trade (lot/fee checks) → NAV curve + team ranking bars

The other tabs (Overview / Holdings / Research / Statements / Paper Trading / Strategy / Market / Ledger / Health)
are views of the conversation results, not duplicate form entries.

Core features

  • 100% local data: everything lives in a local SQLite database. Optional passphrase-protected encrypted backups (PBKDF2 + Fernet); the passphrase is never stored.
  • Never fabricates numbers: amounts, P&L, risk metrics, technical indicators, backtest results and statement ratios are all computed by deterministic engines; the model only classifies and writes prose. At runtime the model only sees read-only tools.
  • Domestic models first: unified access via LiteLLM, defaulting to DeepSeek / Doubao / Qwen / Kimi — zero friction on Chinese platforms. Fully usable without any model configured.
  • Multi-agent orchestration: a LangGraph graph (supervisor pipeline), plus a "finance department mode" that splits one request into tickets, runs departments in parallel, and summarizes for approval.
  • MCP protocol: all finance tools are exposed as a standard MCP Server via fastmcp — Cursor / Claude Code can query your local data directly.
  • Stock research engine: technical indicators (MA/MACD/RSI/BOLL/KDJ) + rule-based signal synthesis + bull/bear bias; statistical forecasting (linear trend + Monte-Carlo GBM percentile band, fixed reproducible seed); MA-cross and DCA strategy backtests (return, annualized, drawdown, Sharpe, win rate, profit factor, equity curve, trade details).
  • Statement analysis engine: paste three-statement JSON → 20+ metrics (profitability / solvency / efficiency / growth / cash-flow quality) + DuPont decomposition + YoY trends + three-cashflow structure + rule-based anomaly alerts (goodwill, receivables, inventory, cash quality…) + a templated report.
  • Investment strategy engine: portfolio risk metrics (volatility / Sharpe / Sortino / max drawdown / Beta / VaR) against a benchmark, target-allocation rebalancing, valuation percentile, DCA plans and FIRE progress.
  • Long-term memory: preferences live in a local table and are recalled with BM25; memory never leaves the machine.
  • 3-level quote fallback: Eastmoney → Sina → local snapshot, clearly labeled when offline.
  • PWA: installable on desktop and mobile.

Interface

Two surfaces, each with a clear job:

  • Chat is the entry point — record an expense, ask a question.
  • Finance workbench follows stock-broker conventions: nine tabs, each a decision dashboard of
    "metric strip + chart + detail table".

Navigation: a persistent session sidebar (chat) plus nine top tabs
(Overview / Holdings / Research / Statements / Paper Trading / Strategy / Market / Ledger / Health).
The main area switches pages; "Back to chat" returns to the conversation.

Width Layout
≥1280 Session sidebar (drag to resize) + main area (chat centred at 48rem, finance pages at 1200px)
768–1279 Sidebar kept; finance two-column layouts collapse to one
<768 Compact top bar + five bottom tabs (Chat / Finance / Holdings / Scheduled / Settings), rest in a drawer

Highlights:

  • Holdings: summary strip → concentration warnings → table + P&L contribution chart, with
    concentration / sector / risk columns on the right.
  • Research: quote strip → technical metric cards (MA alignment / RSI / MACD / BOLL / KDJ) →
    zoomable candlestick chart (A-share red-up/green-down, MA + BOLL overlay toggle, daily/weekly/monthly) →
    signal stream → statistical forecast panel (trend line + Monte-Carlo 5%-95% band) →
    strategy backtest (MA-cross / DCA switch, tunable params, metric strip + equity curve + trade log).
  • Paper Trading: team virtual accounts with event-sourced positions — open account, trade (A-share lots, commission + stamp tax), per-account NAV curves, holdings donut, and team ranking bars
  • Statements: three-statement JSON input (with sample) → four metric-card groups →
    revenue & net profit / margin / solvency / cash-flow trend charts → three-cashflow stacked chart +
    DuPont bar chart → five-dimension financial radar → multi-period comparison table →
    anomaly alert stream → templated report → local save & re-analyze.
  • Strategy: portfolio risk metrics and equity curve vs benchmark, rebalance checklist, valuation
    percentile, DCA plans and FIRE progress.
  • Market: watchlist and holdings with 60-day sparklines, plus a detail panel (trend, period change,
    60-day high/low, full K-line).
  • Ledger: one-sentence entry plus a standard transaction table.
  • Health: score, five-dimension bars, a "fix first" list, and per-dimension advice.
  • Settings uses a left nav with three groups on desktop and a horizontal segmented bar on mobile
    (Basics / AI & automation / Data & security).
  • Sidebar width is remembered (localStorage), double-click the divider to reset; panels trap and
    restore focus, Esc closes.
  • Only chat code loads on first paint; charts / research / statements / department board / inbox are lazy-loaded.

Screenshots: cd frontend && node scripts/ui-audit.mjs (every page, into out/ui-audit/);
README images: node scripts/readme-shots.mjs (writes docs/screenshots/).

Screenshots

Chat Answer: plan + snapshot + actions
Chat Answer
Overview Holdings
Overview Holdings
Market: list + detail Ledger
Market Ledger
Health check Settings
Health Settings
Command palette (Ctrl+K) Dark mode
Command palette Dark
Mobile: chat Mobile: finance
Mobile chat Mobile finance
Investment strategy: risk / rebalance / valuation / DCA / FIRE
Strategy

More in docs/screenshots/.

Quick start

Requirements: Python 3.10+, Node.js 18+.

Fastest path (Docker)

docker compose up -d --build   # single container, port 8787, volume moneyhelper-data

One-click (recommended for development)

scripts/dev.sh        # Windows (Git Bash) / macOS / Linux — backend 8788 + frontend 5198
scripts/dev.sh --prod # production mode: build once, serve on a single port
start.bat             # Windows: creates the venv, installs deps, opens two windows
start.bat --prod      # Windows production mode: one window, one port

The scripts create the virtualenv, install dependencies and check port conflicts; they pick
Scripts/ or bin/ automatically per platform.

Manual

# Backend (run inside backend/)
cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env   # optional: fill LLM_* to enable a model
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8788

# Frontend dev mode (/api proxied to 8788)
cd frontend
npm install && npm run dev    # http://127.0.0.1:5198

# Or production mode: build once, served by the backend on one port
cd frontend && npm run build  # then open http://127.0.0.1:8788

The database lives at backend/data/wealth.db by default (MONEYHELPER_DATA_DIR / MONEYHELPER_DB_PATH override it; empty values fall back to the default).

A fresh database starts empty with chat-style onboarding; everything works without an AI key.

Tech stack

Layer Tech
Frontend React 19 + Vite + Tailwind 4 · ECharts · TanStack Table · PWA
Backend FastAPI + LangGraph multi-agent orchestration + deterministic engine
Data SQLite (aiosqlite + WAL) · encrypted backups (PBKDF2 + Fernet)
AI LiteLLM unified access · local BM25 long-term memory · fastmcp
Quotes Eastmoney → Sina → local snapshot, 3-level fallback

Architecture

flowchart LR
    FE[React SPA] --> API[FastAPI REST + SSE + static hosting]
    API --> G[LangGraph orchestration, supervisor pipeline]
    API --> D[Finance department mode, parallel tickets]
    G --> T[Tool layer, 27 deterministic tools]
    D --> T
    T --> K[Deterministic engine, single source of truth]
    T --> DB[(Local SQLite)]
    T --> Q[3-level quote fallback]
    G --> L[LiteLLM model access]
    G --> M[local BM25 memory]
    API --> MCP[MCP Server /mcp · 36 tools]

Principle: the framework orchestrates; the engine computes. The model only appears at classification and finalization; any failure degrades to the deterministic path. Full architecture with diagrams: docs/architecture.md.

Key invariants:

  • Write tools are invisible to the model (removed at both schema and implementation layers); the model cannot edit the ledger.
  • Amounts, P&L and risk metrics are computed only by analysis / calculations.
  • Long-term memory is fully local (BM25); memory content never leaves the machine.
  • Confirmable write actions use atomic claiming (claim_pending_action), so a token executes exactly once.

Repository layout

backend/app/
  main.py            FastAPI entry: REST + SSE + auth + static hosting
  db/                Data layer (domain modules): ledger / portfolio / budgets /
                     debts / goals / memory / history / audit / backup / users ...
  routes/            Routes: budgets / settings / goals / market / import ...
  agents/            Multi-agent config: supervisor / bookkeeping / portfolio
  agent_graph.py     LangGraph graph: supervisor + specialized nodes + routes
  department.py      Finance department mode: tickets → parallel → summary
  analysis.py        Deterministic engine: positions / cashflow / debt / risk
  calculations/      Portfolio risk / rebalance / valuation / DCA / FIRE models
  tools.py           Agent tool layer: 27 function-calling tools
  quotes.py          Quotes: Eastmoney → Sina → snapshot fallback + cache
  nlparse.py         One-sentence bookkeeping: rule engine + AI fallback
  llm.py             LiteLLM unified model access
  mem.py             long-term memory (local BM25, no network)
  mcp_server.py      MCP Server exposing finance tools
  backup.py          Local encrypted backup, passphrase never stored
frontend/src/
  App.tsx            Adaptive layout: resizable sidebar on desktop / bottom nav on mobile
  components/        ChatView / Dashboard / HoldingsView / MarketView ...
  lib/               api / store / i18n (zh+en) / charts / format
docs/                Deploy / config / workflow / architecture / planning

Docs

Doc Contents
Quick start Up and running in 5 minutes
Deployment Local / Docker / external access / backup migration (中文)
Configuration Env vars + settings + AI endpoint cheat-sheet (中文)
Workflows Every conversation pattern (中文)
Architecture Mermaid diagrams + department mode + data reliability
CLI moneyhelper add / ls / report / balance / ask — offline-first, same commands in local or remote mode
Module map Every backend module: size, structure, responsibility
Development guide Code map + add-tool/setting tutorials + release flow (中文)
Progress What is done, what is left, in one page
Roadmap v3 direction → detailed plan
Planning archive Reviews / differentiation / research docs
Changelog Full version history

Tests

# Backend: 906 tests (engine / strategy / quote fallback / agent loop / LangGraph / API / backup / MCP ...)
cd backend && .venv/bin/python -m pytest tests -q
cd backend && .venv/bin/python -m ruff check app tests

# Frontend: tsc + build + 111 unit tests + 21 Playwright e2e specs
cd frontend && npm run build
cd frontend && npm run test:e2e

CI covers backend ruff (app + moneyhelper package) + pytest, frontend tsc + vitest + build,
plus a hygiene job: no files over 1MB, and mkdocs build --strict must pass.

Data & privacy

  • All personal data lives in local SQLite; quotes use public Eastmoney/Sina endpoints; model calls go only to the endpoint you configured.
  • Encrypted backups recommended; plaintext export shows a strong warning. No telemetry, no tracking, no third-party analytics.
  • Auth: when API_TOKEN is set, all /api/* require Bearer or ?token=; without a token, only localhost and the ALLOWED_HOSTS allowlist are accepted.

Disclaimer

Everything this software outputs (health checks, reports, AI answers, suggestions) is for reference only and does not constitute investment advice. Markets carry risk.

Contributing

Topics: personal-finance finance-assistant ai-agent langgraph fastapi react sqlite local-first mcp pwa

Reviews (0)

No results found