monzo-mcp 是一个面向英国 Monzo 银行 API 的 MCP（Model Context Protocol）服务器，通过 Claude Code 或任何 MCP 客户端提供对银行数据的只读访问。
用途
该工具用于在 MCP 客户端中安全地查询 Monzo 账户信息，包括账户、余额、储蓄罐（pots）、交易记录以及支出分析。它与其他 Monzo MCP 实现的主要区别在于：不使用会于 6 小时后过期的原始 bearer token，而是处理完整 OAuth 流程并自动刷新 token。
主要能力
- 7 个只读工具：无写操作，不涉及资金移动。
- OAuth 自动刷新：token 自动刷新，无需手动重新生成。
- 本地交易缓存：SQLite 数据库持久保存交易，可存活于 Monzo 的 90 天 SCA 窗口之外。
- 按需自动同步：缓存读取工具若发现当天尚未同步，会自动执行增量同步，通常无需手动调用 monzo_sync。
- 支出分析：按类别分解、热门商户、月度对比。
- 交易搜索：按商户、收款方（对手方）、描述或备注搜索已缓存的历史记录。
- 对手方详情：银行转账（faster payments、p2p、Bacs）会缓存收款人姓名、sort code 和账号。
使用方式
环境要求
- Python 3.13+（在 3.13 和 3.14 上测试，支持 Linux、macOS、Windows，并有 CI 覆盖）
- uv（推荐）或 pip
- 一个 Monzo 账户，并在 developers.monzo.com 注册 OAuth 客户端 注意：该包不在 PyPI 上（该名称属于无关项目），而是发布容器镜像，详见 Docker 部分。
源码安装步骤
- 注册 Monzo OAuth 客户端：前往 developers.monzo.com 创建 OAuth 客户端，将重定向 URL 设为 http://localhost:6600/callback，记录 Client ID 和 Client Secret。
- 认证：运行认证命令后会打开浏览器进行 Monzo OAuth，授权后需在 5 分钟内在 Monzo App 中批准登录，以获得完整交易历史访问权限（Monzo 的 SCA 窗口）。
- 在 Claude Code 中注册：Windows 上控制台脚本位于 .venv\Scripts\monzo-mcp.exe。注册后在 Claude Code 中运行 monzo_sync 填充本地交易缓存，应在认证后立即执行以利用 SCA 窗口（最多约 11 个月历史）。
Docker 使用
镜像发布在 ghcr.io/partymola/monzo-mcp，标签带 v 前缀（:vX.Y.Z），:latest 跟随最新发布。容器需要挂载卷，凭据和交易缓存位于 /data；未挂载时容器仍会启动，但所有工具报告未配置，且授权内容在容器被替换后丢失。需先按步骤 1 注册 OAuth 客户端（认证时会提示输入 Client ID 和 secret，之后无法补充）。重定向 URL 与源码安装相同。认证时发布的端口仅用于该步骤，使 OAuth 重定向能到达容器；绑定到 127.0.0.1 可将回调监听器限制在本地网络。容器无浏览器，需复制其打印的 URL。随后在 Monzo App 中于 5 分钟内批准登录，然后复用同一卷注册服务器（-i 为必需，因为服务器通过 stdin/stdout 讲 JSON-RPC）。注册后应立即调用 monzo_sync，因为 11 个月回填在 Monzo App 批准后 5 分钟关闭，错过则只能获得 90 天数据且无错误提示。若希望文件可读，可使用 bind mount 替代命名卷；容器以 root 运行并写入仅所有者可读的凭据，不加 --user 会导致文件归 root 所有。
配置
所有配置通过环境变量（可选）。容器镜像将前两个变量设在 /data，因为包相对默认路径会解析到解释器的 lib 目录而无法挂载；第三个设为 0.0.0.0，因为发布的端口到达容器桥接接口，localhost 绑定会拒绝。凭据文件（由 monzo-mcp auth 创建）：config/monzo_client.json（OAuth 客户端 ID 和 secret）、config/monzo_tokens.json（访问和刷新 token，自动刷新）。
Monzo SCA 窗口
Monzo 的强客户认证（SCA）限制交易历史访问：在 App 批准后 5 分钟内可获取最多约 11 个月历史；窗口过期后仅能获取最近 90 天。本地 SQLite 缓存永久保留所有已同步交易，因此应在 monzo-mcp auth 后尽快运行 monzo_sync。若需回填特定范围，可向 monzo_sync 传入 since 参数（ISO 日期如 2026-01-01 或日期时间如 2026-01-01T14:30:00Z）。最近 90 天内随时可用；更早范围仅能在 SCA 窗口内获取，窗口外请求会被拒绝，且同步会静默地只抓取比最新缓存交易更新的内容。较旧的缓存交易只有在重新抓取后才会获得新版本添加的字段（例如银行转账的对手方/收款方详情），认证后完整同步会为其重新拉取的历史执行此操作。
限制与安全
- 零写工具：无法发送资金、在储蓄罐之间移动资金或修改交易。
- Monzo API 本身无法向外部账户发送资金。
- Token 以 JSON 文件存储在 config/ 目录（已加入 gitignore）。
- 所有 API 调用均为使用 Bearer token 认证的 GET 请求。
故障排查
- 出现 “SCA required” 或仅有 90 天历史：重新运行 monzo-mcp auth 并在 5 分钟内在 Monzo App 批准登录，然后立即同步。
- Token 过期 / 无刷新：重新运行 monzo-mcp auth 重新授权。
- “No transaction data available”：缓存为空，认证后调用 monzo_sync（或任一缓存读取工具，会自动同步）一次。
- Docker 下所有工具报告 “not configured” 或认证无法在重启后保留：/data 未挂载；需将同一卷传给 auth 运行和服务器。
- auth 在批准后卡在 “Waiting for callback...”：回调未送达，按 Ctrl-C 重跑；Docker 下检查端口已发布（-p 127.0.0.1:6600:6600）。
开发与许可
开发环境搭建、测试工作流和 pre-commit 钩子见 CONTRIBUTING.md，变更记录见 CHANGELOG.md。许可为 GPL-3.0-or-later，详见 LICENSE。
