monzo-mcp

monzo-mcp

用于 Monzo 银行 API 的 MCP 服务。通过 Claude Code 或任何 MCP 客户端，以只读方式访问账户、余额、储蓄罐、交易记录和支出分析。

与其他使用原始 bearer 令牌（有效期为 6 小时）的 Monzo MCP 实现不同，本服务支持完整的 OAuth 流程和自动令牌刷新。

功能

• 7 个只读工具——不执行写入操作，不转移资金
• OAuth 自动刷新——令牌会自动刷新，无需手动重新生成
• 本地交易缓存——SQLite 数据库可在 Monzo 的 90 天 SCA 窗口结束后继续保留数据
• 按需自动同步——如果缓存当天尚未同步，读取缓存的工具会自动执行增量同步，因此通常无需手动调用 monzo_sync
• 支出分析——类别细分、热门商户、月环比
• 交易搜索——可在缓存的历史记录中按商户、收款人（交易对手）、描述或备注搜索
• 交易对手详情——银行转账（快速支付、p2p、Bacs）会连同收款人的姓名、sort code 和账号一起缓存

工具

工具	描述	数据来源
monzo_list_accounts	列出账户及其类型和 ID	实时 API
monzo_get_balance	当前余额和今日支出	实时 API
monzo_list_pots	储蓄罐和余额	实时 API
monzo_sync	将交易记录同步到本地缓存	实时 API -> SQLite
monzo_list_transactions	列出／筛选缓存的交易记录	本地缓存（数据过期时自动同步）
monzo_search_transactions	按商户／收款人／描述／备注搜索	本地缓存（数据过期时自动同步）
monzo_spending	支出分析和类别细分	本地缓存（数据过期时自动同步）

前提条件

• Python 3.13+（CI 已在 Linux、macOS 和 Windows 上使用 3.13 和 3.14 进行测试）
• uv（推荐）或 pip
• 一个 Monzo 账户，并在 developers.monzo.com 注册 OAuth 客户端

安装

git clone https://github.com/partymola/monzo-mcp.git
cd monzo-mcp
uv venv --python 3.13 .venv
uv pip install -e .

此软件包未发布到 PyPI——该名称已被一个无关项目使用。这里发布的是容器镜像；请参阅 Docker。

设置

1. 注册 Monzo OAuth 客户端

前往 developers.monzo.com 并创建 OAuth 客户端：

• 将重定向 URL 设为 http://localhost:6600/callback
• 记下你的 Client ID 和 Client Secret

2. 身份验证

monzo-mcp auth

这会打开浏览器以进行 Monzo OAuth 授权。授权后，请在 5 分钟内于 Monzo 应用中批准登录，以便访问完整交易历史（Monzo 的 SCA 窗口）。

3. 在 Claude Code 中注册

claude mcp add -s user monzo -- /path/to/monzo-mcp/.venv/bin/monzo-mcp

在 Windows 上，控制台脚本位于 .venv\Scripts\monzo-mcp.exe。

4. 首次同步

在 Claude Code 中运行 monzo_sync，以填充本地交易缓存。请在身份验证后立即执行，以便利用 SCA 窗口获取最多 11 个月的历史记录。

Docker

镜像发布在 ghcr.io/partymola/monzo-mcp。标签带有 v 前缀（:vX.Y.Z），而 :latest 指向最新版本。

**容器需要挂载卷。**凭据和交易缓存位于 /data 下；如果这里没有挂载任何内容，容器仍会启动，但每个工具都会报告尚未配置，而且容器替换后，你授权的任何内容都会丢失。

首先，按照 设置步骤 1 注册 OAuth 客户端——auth 会提示你输入客户端 ID 和密钥，之后无法再提供这些信息。重定向 URL 为 http://localhost:6600/callback，与从源码安装时相同。

在一个命名卷中完成一次身份验证。在运行之前决定是否改用绑定挂载——之后再切换就意味着需要重新授权：

docker volume create monzo-mcp-data
docker run --rm -it \
  -v monzo-mcp-data:/data \
  -p 127.0.0.1:6600:6600 \
  ghcr.io/partymola/monzo-mcp:latest auth

发布端口仅在此步骤中需要，以便 OAuth 重定向能够到达容器。将端口绑定到 127.0.0.1 可确保回调监听器不会暴露在你的网络上。不会打开浏览器——容器中没有浏览器——因此请复制它打印出的 URL。然后在 5 分钟内于 Monzo 应用中批准登录（请参阅 Monzo SCA 时限）。

然后注册服务，并复用同一个卷：

claude mcp add -s user monzo -- \
  docker run --rm -i -v monzo-mcp-data:/data ghcr.io/partymola/monzo-mcp:latest

必须使用 -i——服务通过标准输入和标准输出传输 JSON-RPC。

**立即同步。**在你于 Monzo 应用中批准后 5 分钟，11 个月的历史回填时限就会结束（请参阅 Monzo SCA 时限）；而且这种方式比从源码安装的流程更长——因此，服务注册后请立即调用 monzo_sync。错过时限后，你将悄无声息地只能获取 90 天的数据，不会收到错误提示。

若要将文件保存在你可以读取的位置，请改用绑定挂载，而不是命名卷。容器以 root 身份运行，并以仅所有者可读写的权限写入凭据，因此如果不使用 --user，这些文件将归 root 所有：

mkdir -p ~/monzo-mcp-data/config
docker run --rm -it \
  -v ~/monzo-mcp-data:/data \
  --user $(id -u):$(id -g) \
  -p 127.0.0.1:6600:6600 \
  ghcr.io/partymola/monzo-mcp:latest auth

在服务命令中传入相同的 -v 和 --user。请先创建目录——对命名卷使用 --user 会失败，因为卷会从镜像初始化为 root 所有。

命令行

monzo-mcp              Start the MCP server (stdio transport)
monzo-mcp auth         Interactive OAuth setup (opens the browser)
monzo-mcp --version    Print the installed package version

配置

所有配置均通过环境变量设置（可选）：

变量	默认值	说明
MONZO_MCP_CONFIG_DIR	<package>/config/	OAuth 凭据和令牌的目录
MONZO_MCP_DB_PATH	<package>/monzo.db	SQLite 交易缓存的路径
MONZO_MCP_CALLBACK_HOST	localhost	auth 回调服务绑定的接口。不会影响重定向 URI

容器镜像将前两个变量设置在 /data 下，因为包相对路径的默认值会指向解释器的 lib 目录，而该目录无法挂载。第三个变量设为 0.0.0.0，因为发布的端口会通过容器的桥接接口进入，而绑定到 localhost 会拒绝连接。

凭据文件（由 monzo-mcp auth 创建）：

• config/monzo_client.json - OAuth 客户端 ID 和密钥
• config/monzo_tokens.json - 访问令牌和刷新令牌（自动刷新）

Monzo SCA 时限

Monzo 的强客户身份验证（SCA）会限制交易历史记录的访问：

• 应用批准后的 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 本身无法向外部账户汇款
• 令牌以 JSON 文件的形式存储在 config/ 目录中（已添加到 gitignore）
• 所有 API 调用均为带有 Bearer 令牌身份验证的 GET 请求

故障排查

• “需要 SCA”或只能查看 90 天的历史记录——重新运行 monzo-mcp auth，并在 5 分钟内于 Monzo 应用中批准登录，然后立即同步（参见上文的 SCA 时间窗口）。
• 令牌已过期／无法刷新——重新运行 monzo-mcp auth 以重新授权。
• “没有可用的交易数据”——缓存为空；完成身份验证后，调用一次 monzo_sync（或任何读取缓存的工具，它会自动同步）。
• Docker 下所有工具都报告“未配置”，或重启后身份验证状态未保留——/data 没有挂载内容。请参见 Docker；auth 运行和服务必须传入同一个卷。
• 批准后 auth 一直停留在“等待回调...”——回调未送达。按 Ctrl-C，然后重新运行。在 Docker 下，请检查端口是否已发布（-p 127.0.0.1:6600:6600）。

贡献

有关开发环境设置、测试工作流和 pre-commit 钩子，请参见 CONTRIBUTING.md。变更记录见 CHANGELOG.md。

许可证

GPL-3.0-or-later。请参见 LICENSE。