Avie Money Lover MCP / Local Bridge

非官方的 Money Lover 集成，支持两种工作流：

1. MCP 服务器 — 向支持 MCP 的客户端暴露 Money Lover 读写工具。

2. GPT + 本地桥接 — 让 ChatGPT 准备/审查对账单 JSON，而您自己的机器保留 Money Lover 令牌/Cookie 并执行最终导入。

非官方项目。 本仓库与 Money Lover 无关联，未获得其认可或赞助。它使用从 Money Lover Web 应用中观察到的 Web 端点。这些端点、身份验证流程、类别行为以及反机器人要求可能随时更改，恕不另行通知。

它能做什么

• 读取已认证用户信息

• 列出钱包和钱包类别

• 按日期范围读取交易

• 使用交易历史将 Money Lover user_category_v2 源 ID 解析为运行时 ID

• 预览单笔交易而不写入

• 添加带重复保护的交易

• 预览银行/卡对账单批次

• 将支出 − 收入与对账单总额核对

• 标记完全重复、疑似重复、未解析类别和待审查行

• 仅在明确确认后按顺序导入

• 通过回读验证已创建的交易

• 部分导入后可安全重新运行：完全重复项会被跳过

Related MCP server: monarch-mcp

要求

• Windows 10/11、macOS 或 Linux

• Node.js 22+

• 您自己拥有的 Money Lover 账户

• 为可靠写入：全新的 wallet-owner 会话、当前浏览器 Cookie/cf_clearance（如需要），以及匹配的浏览器 User-Agent

快速开始

git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm test

Windows 辅助程序设置

scripts\setup-windows.cmd

仅在当前 shell 中设置凭据：

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"

然后运行：

scripts\doctor.cmd

推荐的 GPT + 本地工作流

Bank/card statement
        ↓
ChatGPT extracts + categorizes
        ↓
statement JSON
        ↓
local preview
        ↓
review / duplicate / reconciliation checks
        ↓
explicit IMPORT confirmation
        ↓
Money Lover
        ↓
local verification report

不要将 Money Lover 令牌、刷新令牌、密码、浏览器 Cookie 或 cf_clearance 粘贴到 ChatGPT、GitHub issue、日志或截图中。ChatGPT 只需要对账单以及生成的预览/结果 JSON。

预览对账单

scripts\preview.cmd data\your-statement.json

审查后导入

scripts\import.cmd data\your-statement.json

导入器要求您准确输入：

IMPORT

之后才会开始写入。

完整越南语指南请参阅 docs/HUONG_DAN_SU_DUNG.md。

观察到的 API 行为

已认证请求当前使用：

Authorization: AuthJWT <access_token>

观察到的端点：

写入操作可能需要类似浏览器的请求头和有效的 Cloudflare 会话。支持的环境变量包括：

• MONEYLOVER_ACCESS_TOKEN

• MONEYLOVER_CF_CLEARANCE

• MONEYLOVER_COOKIE

• MONEYLOVER_USER_AGENT

• MONEYLOVER_TIMEOUT_MS

• MONEYLOVER_CATEGORY_LOOKBACK_DAYS

• MONEYLOVER_WRITE_DELAY_MS

批量对账单格式

从 data/example-statement.json 开始。完整字段文档见 docs/STATEMENT_FORMAT.md。

预览：

npm run preview -- data\your-statement.json

导入：

npm run import -- data\your-statement.json

可选标志：

• --allow-review — 在您检查后，包含有意保留在 review 中的行

• --allow-mismatch — 绕过对账单核对保护；仅在您了解差异原因时使用

• --allow-shared-wallet — 绕过所有者安全检查；共享钱包写入仍可能失败

• --confirm IMPORT — 非交互式确认；不建议常规手动使用

安全默认设置

导入器在以下情况下拒绝写入：

• 任何行处于 blocked 状态

• 存在 review 行，除非提供了 --allow-review

• 对账单核对差异非零，除非提供了 --allow-mismatch

• 已认证用户不是钱包所有者，除非提供了 --allow-shared-wallet

• 确认内容不完全是 IMPORT

金额必须是正数。

类别 v2

某些账户会从 /category/list 暴露源/模板类别 ID，而 /transaction/add 期望的是不同的运行时类别 ID。桥接程序会从现有交易中学习此映射关系。

如果某个类别从未在历史记录中出现过，请复制：

config/runtime-category-overrides.example.json

到：

config/runtime-category-overrides.json

并添加从真实浏览器交易请求中观察到的运行时 ID。本地覆盖文件会被 Git 忽略。

公共仓库安全

该仓库默认配置为避免提交本地财务数据：

• data/*.json 会被忽略，但经过脱敏处理的示例除外

• out/ 会被忽略

• .env* 会被忽略

• 本地运行时类别覆盖会被忽略

• 本地会话辅助文件会被忽略

推送前，请运行：

npm run repo:check
npm test

然后手动检查 git status。

安全

如果令牌、密码、刷新令牌、浏览器 Cookie 或 cf_clearance 值曾经泄露，请将其视为已泄露，并轮换/撤销该会话。请参阅 SECURITY.md。

贡献

欢迎提交错误报告和拉取请求。在提交更改之前，请阅读 CONTRIBUTING.md。切勿在 issue 或测试夹具中包含真实的财务对账单、账户标识符、令牌或 Cookie。

文档

• 越南语使用指南

• 对账单 JSON 格式

• 架构

• GitHub 发布指南

• 安全策略

• 更新日志

• GPT 对账单规范化提示词

• GPT 预览审查提示词

许可证

MIT — 请参阅 LICENSE。