avie-moneylover-mcp
This unofficial Money Lover MCP server lets an authenticated client read wallet data, preview transactions safely, and write single transactions only after explicit confirmation.
Authenticate —
loginwith Money Lover email/password to obtain an access token (tokens may also be passed per-call via an optionaltokenoverride).Read profile —
get_user_inforeturns the authenticated Money Lover profile.List wallets —
get_walletsenumerates all wallets accessible to the user.List categories —
get_categoriesretrieves categories for a givenwalletId.Read transactions —
get_transactionsfetches transactions for a wallet within astartDate/endDaterange (YYYY-MM-DD).Preview without writing —
preview_transactionresolves the category (by ID, name, or runtime ID) and checks for an exact duplicate, returning a dry-run result.Add one transaction —
add_transactioncreates a single transaction; it requiresconfirmWrite: true, validates category ownership, and blocks exact duplicates unlessallowDuplicateis set.Diagnose write readiness —
diagnose_write_contextgives read-only diagnostics on wallet ownership, browser write configuration, and category-v2 runtime ID mapping.Not included — despite the README, the schema exposes no batch statement preview/import, reconciliation, duplicate-reporting, or category-update tools; all writes are single-transaction and confirmation-gated.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@avie-moneylover-mcp preview my bank statement and check for duplicate transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Avie Money Lover MCP — Cloud + Local Bridge
Unofficial Money Lover integration for three workflows:
Private cloud MCP — use the connector from ChatGPT on desktop and phone through one HTTPS endpoint.
Local MCP (stdio) — connect from a compatible desktop client without publishing an endpoint.
GPT + local bridge — let ChatGPT prepare/review statement JSON while your own machine performs the final import.
Unofficial project. This repository is not affiliated with, endorsed by, or sponsored by Money Lover. It uses web endpoints observed from the Money Lover web app. Those endpoints, authentication flows, category behavior, and anti-bot requirements can change without notice.
What it can do
Read authenticated user info
List wallets and wallet categories
Read transactions by date range
Resolve Money Lover
user_category_v2source IDs to runtime IDs using transaction historyPreview a single transaction without writing
Add a transaction with duplicate protection
Preview and apply category-only transaction updates without delete/recreate workarounds
Preview a bank/card statement batch
Reconcile expense − income against a statement total
Flag exact duplicates, probable duplicates, unresolved categories, and review rows
Import sequentially only after explicit confirmation
Verify created transactions by reading them back
Safely re-run after a partial import: exact duplicates are skipped
Related MCP server: monter-mcp
Requirements
Windows 10/11, macOS, or Linux
Node.js 22+
A Money Lover account you control
For reliable writes: a fresh wallet-owner session, current browser cookie/
cf_clearanceif required, and the matching browser User-Agent
Quick start
git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm testPrivate cloud MCP (recommended for phone use)
This repository includes a stateless Streamable HTTP endpoint at /mcp, single-user OAuth with PKCE, a Dockerfile, and Railway configuration. Secrets stay in the host's environment variables and are never MCP tool arguments.
Deploy and connect it using the cloud deployment guide. In short:
Deploy this repository to Railway.
Add the variables from
.env.examplein Railway; never commit their real values.Generate a public Railway domain and set
MCP_PUBLIC_URLto that exact HTTPS origin.Add
https://YOUR-DOMAIN/mcpas a custom connector in ChatGPT Developer mode.Authorize using
MCP_OWNER_PASSWORD(not your Money Lover password).
Once the connector is enabled for your ChatGPT account, it can be used by supported ChatGPT mobile clients too. Initial custom-connector setup is easiest in ChatGPT web.
Windows helper setup
scripts\setup-windows.cmdSet credentials in the current shell only:
set "MONEYLOVER_ACCESS_TOKEN=YOUR_FRESH_OWNER_TOKEN"
set "MONEYLOVER_CF_CLEARANCE=YOUR_CURRENT_CF_CLEARANCE_VALUE"
set "MONEYLOVER_USER_AGENT=YOUR_EXACT_BROWSER_USER_AGENT"Then run:
scripts\doctor.cmdRecommended GPT + local workflow
Bank/card statement
↓
ChatGPT extracts + categorizes
↓
statement JSON
↓
local preview
↓
review / duplicate / reconciliation checks
↓
explicit IMPORT confirmation
↓
Money Lover
↓
local verification reportDo not paste Money Lover tokens, refresh tokens, passwords, browser cookies, or cf_clearance into ChatGPT, GitHub issues, logs, or screenshots. ChatGPT only needs the statement plus the generated preview/result JSON.
Preview a statement
scripts\preview.cmd data\your-statement.jsonImport after review
scripts\import.cmd data\your-statement.jsonThe importer requires you to type exactly:
IMPORTbefore writes begin.
See docs/HUONG_DAN_SU_DUNG.md for the complete Vietnamese guide.
API behavior observed
Authenticated requests currently use:
Authorization: AuthJWT <access_token>Observed endpoints:
Client method | HTTP | Endpoint |
| POST |
|
| POST |
|
| POST |
|
| POST |
|
| POST |
|
| POST |
|
Writes may require browser-like headers and a current Cloudflare session. Supported environment variables include:
MONEYLOVER_ACCESS_TOKENMONEYLOVER_CF_CLEARANCEMONEYLOVER_COOKIEMONEYLOVER_USER_AGENTMONEYLOVER_TIMEOUT_MSMONEYLOVER_CATEGORY_LOOKBACK_DAYSMONEYLOVER_WRITE_DELAY_MSMCP_PUBLIC_URLMCP_AUTH_SECRETMCP_OWNER_PASSWORD
Batch statement format
Start from data/example-statement.json. Full field documentation is in docs/STATEMENT_FORMAT.md.
Preview:
npm run preview -- data\your-statement.jsonImport:
npm run import -- data\your-statement.jsonOptional flags:
--allow-review— include rows intentionally left inreviewafter you inspect them--allow-mismatch— bypass statement reconciliation protection; use only when you understand the discrepancy--allow-shared-wallet— bypass the owner safety check; shared-wallet writes may still fail--confirm IMPORT— non-interactive confirmation; not recommended for ordinary manual use
Safety defaults
The importer refuses to write when:
any row is
blockeda
reviewrow exists unless--allow-reviewis suppliedthe statement reconciliation difference is non-zero unless
--allow-mismatchis suppliedthe authenticated user is not the wallet owner unless
--allow-shared-walletis suppliedconfirmation is not exactly
IMPORT
Amounts must be positive numbers.
Single-transaction category updates use a separate safety workflow:
Call
preview_update_transactionwith the wallet, transaction, current date, and target category.Review the returned before/after category and short-lived
previewId.Call
update_transactionwith thatpreviewIdand literal confirmationUPDATE.
The update is blocked if the authenticated session is not the wallet owner or if the transaction changed after preview. The connector uses Money Lover's observed /transaction/edit endpoint, preserves the existing transaction ID and non-category fields, and reads the transaction back to verify the result.
Category v2
Some accounts expose a source/template category ID from /category/list, while /transaction/add expects a different runtime category ID. The bridge learns this mapping from existing transactions.
If a category has never appeared in history, copy:
config/runtime-category-overrides.example.jsonto:
config/runtime-category-overrides.jsonand add the runtime ID observed from a real browser transaction request. The local override file is ignored by Git.
Public-repo safety
The repository is configured to avoid committing local financial data by default:
data/*.jsonis ignored except the sanitized exampleout/is ignored.env*is ignoredlocal runtime category overrides are ignored
local session helper files are ignored
Before pushing, run:
npm run repo:check
npm testThen inspect git status manually.
Security
If a token, password, refresh token, browser cookie, or cf_clearance value is ever exposed, treat it as compromised and rotate/revoke the session. See SECURITY.md.
Contributing
Bug reports and pull requests are welcome. Please read CONTRIBUTING.md before submitting changes. Never include real financial statements, account identifiers, tokens, or cookies in issues or test fixtures.
Documentation
License
MIT — see LICENSE.
Available Tools
8 toolsadd_transactionAdd a Money Lover transactionA
Create one transaction only after explicit confirmation. Validates category ownership and blocks exact duplicates by default.
Inputs: date (required), amount (required), walletId (required), confirmWrite (required), +7 more.
diagnose_write_contextDiagnose Money Lover write contextC
Read-only diagnostics for wallet ownership, browser write config, and category-v2 runtime mapping.
Inputs: walletId (required), token, categoryId, categoryName, +1 more.
get_categoriesList Money Lover categoriesB
Retrieve categories for a specific wallet.
Inputs: walletId (required), token.
get_transactionsGet Money Lover transactionsB
Fetch transactions for a wallet between two dates.
Inputs: endDate (required), walletId (required), startDate (required), token.
get_user_infoGet Money Lover user infoC
Retrieve the authenticated Money Lover profile.
Inputs: token.
get_walletsList Money Lover walletsB
List all wallets accessible to the authenticated user.
Inputs: token.
loginLogin to Money LoverA
Authenticate with Money Lover and return an access token.
Inputs: email (required), password (required).
preview_transactionPreview a Money Lover transactionB
Resolve a category and check for an exact duplicate without writing anything.
Inputs: date (required), amount (required), walletId (required), note, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clear, distinct purpose: login, user info, wallets, categories, transactions (list, preview, add), and diagnostics. No two tools overlap in functionality.
All tool names follow a consistent verb_noun pattern (e.g., get_wallets, add_transaction, diagnose_write_context). Although verbs vary, they match the action type appropriately, and the naming is uniform and predictable.
With 8 tools, the server is well-scoped for a personal finance app. It covers authentication, read operations, transaction creation, and diagnostics without bloat or redundancy.
The tool set covers authentication, reading of user/wallets/categories/transactions, and adding transactions. However, it lacks update and delete operations for any resource, which are notable gaps in a typical CRUD lifecycle. This could hinder agents from correcting mistakes or modifying data.
Maintenance
Related MCP Connectors
Normalize bank statements (CSV, camt, MT940, OFX, QIF) to JSON, analyze, export.
Normalize bank statements (CSV, camt, MT940, OFX, QIF) to JSON, analyze, export.
Read Yomio expense, income, account, budget, and spending data in an MCP-compatible AI client.
Multi-currency budgeting: read and update your accounts, transactions, categories and budgets.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables interaction with Monarch Money data via MCP tools for accounts, budgets, and transactions.689 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables local analysis of personal finance data from a Monter JSON export, answering questions about spending, subscriptions, debts, and more via MCP-capable assistants without any cloud servers.MIT
- AlicenseNot gradedqualityBmaintenanceEnables full CRUD and lending management for Money Lover transactions, wallets, categories, and lending records via MCP, with both local and HTTP transports.229 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables reading and changing personal finance data—accounts, transactions, categories, budgets, and reminders—and generating reports through 28 MCP tools over local stdio or authenticated remote HTTP.MIT