NZ Open Banking MCP (Akahu)

向 AI 助手询问你的新西兰银行账户信息，无需将银行凭据交给任何新的人。nz-openbank-mcp 是一个模型上下文协议服务，通过你创建并控制的 Personal App 与 Akahu（新西兰开放金融服务）通信。它在你自己的设备上运行，默认以只读模式启动，并在进行任何更改前征求确认。

非官方项目。与 Akahu 或任何银行均无关联，也未获得其认可。

试着这样提问

• “上个月我在杂货上花了多少钱？分别在哪些商店消费的？”
• “我在支付哪些订阅服务？每年费用是多少？”
• “显示我所有账户的余额。”
• “找出我今年付给房东的所有款项。”
• “有没有尚未结算的待处理交易？”
• “比较我 9 月和 10 月的外出就餐支出。”

为何可以放心尝试

默认只读	写入工具会拒绝执行，直到你将 AKAHU_READ_ONLY=false。
每次写入都需征求同意	启用写入后，每次写入前都会先征求你的同意，并准确显示将要发送的内容。
本地运行，保护隐私	在你的设备上通过 stdio 运行，且只与 api.akahu.io 通信。不会记录令牌或交易内容。
账户号码已屏蔽	只显示银行代码、末四位数字和后缀。
精简且经过测试	基于 Akahu 端点的轻量封装，采用严格类型检查，并在 CI 中强制要求行覆盖率和分支覆盖率达到 100%。

PyPI · Releases · Security policy

它能做什么

该服务提供 14 个工具。其中 10 个仅用于读取；另外 4 个会进行更改，默认关闭，需手动启用。

全部 14 个工具

工具	是否写入？	用途
acct_list_accounts		列出所有已连接账户，显示屏蔽后的号码和余额
acct_get_account		按 ID 获取单个账户
acct_get_account_balance		仅获取单个账户的余额
acct_get_pending_transactions		获取单个账户尚未结算的交易
txn_get_transactions		获取已结算的交易，可按账户、日期、类别或金额筛选（默认 100 条）
txn_get_transaction		按 ID 获取单笔交易
txn_get_transactions_by_ids		在一次请求中获取多笔交易
txn_get_pending_transactions		获取所有账户尚未结算的交易
txn_search_transactions		对描述和商户名称进行不区分大小写的文本搜索；未指定开始日期时，搜索截至结束日期或今天的 90 天内的交易（默认 50 条）
id_get_me		获取 Akahu 用户的个人资料
acct_refresh_all_accounts	是	请求 Akahu 获取所有账户的最新数据
acct_refresh_account	是	请求 Akahu 获取单个账户的最新数据
txn_report_transaction_issue	是	就某笔交易向 Akahu 创建支持工单
id_verify_name	是	将姓名与账户持有人进行核对；需要额外的权限范围（见 限制），且每次调用可能收费

它没有内置消费报告、预算或预测功能。助手会根据交易自行计算，从而让服务保持小巧、易于审计。

获取 Akahu 令牌

1. 登录 my.akahu.nz/developers， 并创建一个 Personal App。
2. 连接你希望助手查看的银行账户。
3. 复制 App Token（app_token_...）和 User Token （user_token_...）。

请像保护密码一样保管这两种令牌。以下安装步骤会避免将它们存入项目文件。

你还需要 uv。插件、Desktop Extension 和通用客户端配置都会使用 uvx 运行服务；它会获取发行版本及匹配的 Python。

安装

使用场景	方式	令牌存放位置
Claude Code	从此仓库的 marketplace 安装插件	OS 钥匙串，安装时提示输入
Claude Desktop	.mcpb Desktop Extension	OS 钥匙串，安装时提示输入
Codex	从此仓库的 marketplace 安装插件	Codex 启动时的环境
Cursor	从此仓库的 marketplace 安装插件	Cursor 插件设置
Grok Build	从此仓库的 marketplace 安装插件	Grok 启动时的环境
claude.ai、ChatGPT、grok.com	使用 OAuth 的可自托管 HTTPS 服务	你的服务端环境
任何支持 MCP 的其他客户端	uvx nz-openbank-mcp	客户端环境

以下所有选项都会以 AKAHU_READ_ONLY=true 和 AKAHU_AUTOMATION_BYPASS=false 启动。

Claude Code

/plugin marketplace add thatskiff33/nz-openbank-mcp
/plugin install nz-openbank-mcp@nz-openbank

Claude Code 会要求输入两个令牌和两个安全设置。随后，/mcp 应会将该服务列为已连接。之后若要更改设置，请打开 /plugin，选中插件并选择 Configure options。更多详情（包括更新和移除）请参阅 plugin/README.md。

Claude Desktop

从最新版本下载 nz-openbank-mcp-X.Y.Z.mcpb 并打开，或使用 Settings -> Extensions -> Advanced -> Install Extension。Desktop 会显示一个表单，用于填写令牌和设置。若要更新，请安装更新版本的 .mcpb。

Claude Code 插件不能在 Claude Desktop 中使用，因为 Desktop 目前无法收集插件设置。

Codex、Grok Build

这两个宿主都无法提示输入插件密钥，因此令牌来自启动宿主时所在环境。请从操作系统的密钥存储中读取令牌，而不要将其写入点文件：

# macOS
export AKAHU_USER_TOKEN="$(security find-generic-password -s akahu-user-token -w)"
export AKAHU_APP_TOKEN="$(security find-generic-password -s akahu-app-token -w)"
# Linux (libsecret)
export AKAHU_USER_TOKEN="$(secret-tool lookup service akahu-user-token)"
export AKAHU_APP_TOKEN="$(secret-tool lookup service akahu-app-token)"

在 Codex、Grok Build 和 Cursor 中，如果宿主启动时的环境已设置 AKAHU_READ_ONLY 或 AKAHU_AUTOMATION_BYPASS，则会覆盖安全默认值。

Codex：

codex plugin marketplace add thatskiff33/nz-openbank-mcp
codex plugin add nz-openbank-mcp@nz-openbank
codex mcp list          # shows the akahu server

Codex 只会将四个 AKAHU_* 设置传递给服务。使用 codex plugin marketplace upgrade nz-openbank 进行更新。

Grok Build：

grok plugin marketplace add thatskiff33/nz-openbank-mcp
grok plugin install nz-openbank-mcp --trust
grok mcp doctor akahu   # should report 14 tools

Grok 也会加载 Claude Code 插件。请只在其中一个宿主中安装，否则会出现两个服务副本。

Cursor

agent plugin marketplace add https://github.com/thatskiff33/nz-openbank-mcp

从 Customize 安装 nz-openbank-mcp（或在 Cursor 命令行中使用 /plugins），然后在 Plugins -> Configure 下输入两个令牌。Cursor 会保存令牌，而不是仓库。将安全设置留空即可保留默认值。该服务会显示为 plugin-nz-openbank-mcp-akahu。未在此处设置的选项会回退到 Cursor 启动时所在环境中的设置。若要试用本地检出版本，请使用 --plugin-dir /path/to/nz-openbank-mcp/plugin 启动 Cursor 命令行。

顶部的 Add to Cursor 按钮会安装普通 MCP 条目，而不是插件。它会从 Cursor 启动时所在环境读取 AKAHU_USER_TOKEN 和 AKAHU_APP_TOKEN，因此请按照上文 Codex 部分的说明设置这些变量。

Web 连接器（claude.ai、ChatGPT、grok.com）

Web 助手只能访问公共互联网中的服务。请在 HTTPS 后运行 nz-openbank-mcp-http 入口点，并启用 OAuth；然后在助手中添加自定义连接器（grok.com 用户可前往 grok.com/connectors），并将其指向服务的 /mcp URL。在 OAuth 模式下，此服务充当 OAuth 授权服务，Google 会确认登录者身份，只有获准的 Google 账号或 Workspace 网域可以通过。Google 永远不会看到你的 Akahu 令牌。

设置、Google 客户端、重定向允许列表和安全加固说明见 docs/public-https-streamable-http.md，其中还提供了 systemd 示例，位于 deploy/linux-systemd/。grok.com 的连接器回调 https://grok.com/connectors-oauth-exchange-code/ 不在默认重定向列表中。NZ_OPENBANK_MCP_ALLOWED_REDIRECT_URIS 会替换该列表，因此请一并加入仍需使用的默认条目。

其他 MCP 客户端

将客户端指向此命令，并通过环境变量提供设置：

uvx nz-openbank-mcp            # or pin: uvx --from nz-openbank-mcp==X.Y.Z nz-openbank-mcp

examples/claude_desktop_config.json 展示了大多数采用 JSON 配置的客户端所需的格式。若要在 Claude Desktop 中使用它而不是扩展，请将其合并到配置文件中并重启：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Docker

每个版本也会发布为多架构镜像（amd64 和 arm64），以非 root 用户身份运行，并启用只读模式：

docker run -i --rm -e AKAHU_USER_TOKEN -e AKAHU_APP_TOKEN ghcr.io/thatskiff33/nz-openbank-mcp

不带值的 -e NAME 会从你的 shell 传递变量，因此令牌不会出现在命令行中。对于使用 JSON 配置的客户端，请将 "command": "docker" 与这些参数搭配使用。对于 HTTP 服务，请在镜像中运行 nz-openbank-mcp-http；参见 HTTPS 指南。

设置

服务会从进程环境中读取设置；只有当 AKAHU_ENV_FILE 指定了 env 文件时，才会读取该文件（进程环境中的值优先）。它不会读取工作目录中的 .env 文件。

变量	默认值	含义
AKAHU_USER_TOKEN	（必填）	你的用户令牌
AKAHU_APP_TOKEN	（必填）	你的 Personal App 的 App Token
AKAHU_READ_ONLY	true	拒绝所有写入工具
AKAHU_AUTOMATION_BYPASS	false	跳过两个刷新工具的确认提示
AKAHU_REQUEST_TIMEOUT	10	每次 Akahu 请求的秒数（1 到 120）
AKAHU_LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR 或 CRITICAL
AKAHU_ENV_FILE	（未设置）	要加载的 env 文件的绝对路径；在 Linux 和 macOS 上，该文件必须属于你（或 root），且不可由组用户或其他用户写入
AKAHU_BASE_URL	https://api.akahu.io/v1	必须保持为 api.akahu.io，除非启用了下一项设置
AKAHU_ALLOW_CUSTOM_BASE_URL	false	允许使用其他 API 主机；仅接受进程环境中的设置，绝不从 env 文件中读取

使用自定义 API 主机时，服务会在启动时记录一条警告。只能在你自己的 shell 或主机配置中设置 AKAHU_ENV_FILE 和 AKAHU_ALLOW_CUSTOM_BASE_URL，切勿将它们放入克隆的仓库中的项目文件。

HTTP 入口点有自己的 NZ_OPENBANK_MCP_* 设置，详见 .env.example 和 HTTPS 指南。

写入操作如何受到保护

每个写入工具前都有三项检查：

1. 只读开关。 设置 AKAHU_READ_ONLY=true 时，工具会在任何请求离开你的设备之前拒绝执行。
2. 确认。 启用写入后，服务会通过助手的确认提示请求你批准每次调用。提示会列出即将发送的所有值，例如完整的支持工单评论文本，并用引号括起，同时将隐藏字符显示出来。超过 1,000 个字符的值会被拒绝，而不是缩短。拒绝或关闭提示都会取消调用。
3. 有限绕过。 设置 AKAHU_AUTOMATION_BYPASS=true 时，仅会为 acct_refresh_all_accounts 和 acct_refresh_account 跳过提示；这两个工具只会请求 Akahu 重新同步。每次跳过提示都会被记录，启动横幅会列出这些工具；如果只读模式也处于启用状态，服务将不会在绕过模式下启动。支持工单和姓名检查始终需要确认。

限制

Akahu Personal Apps 无法访问应用级端点，因此本服务不提供类别（交易会内嵌类别信息）、受支持银行列表、付款或 webhook 的工具。

id_verify_name 需要为你的 Personal App 启用相应权限，前往 my.akahu.nz/developers 即可设置；否则 Akahu 会返回 403。

待处理交易没有 ID，在结算前可能会发生变化，并且会标记为 "pending": true。

txn_get_transactions 和 txn_search_transactions 每次调用最多从 Akahu 读取 20 页结果。如果某个时间范围内的结果更多，返回结果会包含 "truncated": true；请使用更窄的日期范围再次查询。

遇到网络错误或 Akahu 服务端错误时，读取操作和账户刷新操作最多会尝试三次。支持工单和姓名检查只会发送一次，因为即使请求超时，也可能已到达 Akahu。对于速率限制（429）响应，每个请求都会重试。

日期和金额

日期采用新西兰日历日（Pacific/Auckland），尽管 Akahu 存储的是 UTC 时间戳。仅包含日期的筛选条件（例如 start_date=2026-10-18）会覆盖整个新西兰日，无论是在范围的哪一端；完整的 ISO 8601 时间戳会原样传递给 Akahu，而 Akahu 会将不带时区偏移的时间戳视为 UTC。金额按各账户的货币格式化，因此 USD 账户会显示为 -USD 9.99。如果账户货币未知，currency 为 null，且 amount 不含货币符号（例如 -1,234.50）；amount_raw 是相同金额的纯数字，四舍五入到分。其他日期格式均不接受。

隐私

• 新西兰账户号码会遮盖，仅显示银行代码、账户号码末四位和后缀。其他格式中，除末四位外的所有数字都会被遮盖。
• 不会记录令牌。不会记录余额和交易内容；请求路径（可能包含 Akahu 账户或交易 ID）会连同状态一起记录。
• 默认情况下，通过 stdio 运行时，服务唯一的网络流量是发往 api.akahu.io 的流量（以及 uvx 下载软件包的流量）。HTTP 模式还会连接 Google 以供登录。
• 账户和日期筛选条件会发送给 Akahu；类别和金额筛选条件则在数据到达后应用。Personal Apps 不提供更细粒度的访问控制，因此令牌可以读取你已连接的所有内容。

隐私政策说明了哪些人可以看到哪些内容，威胁模型列出了各项风险、相应的缓解措施以及仍然存在的风险。

发布文件（wheel、sdist 和 .mcpb）附带 GitHub 构建来源证明，PyPI 上传则通过 Trusted Publishing 完成。要验证下载内容：

gh attestation verify nz-openbank-mcp-X.Y.Z.mcpb --repo thatskiff33/nz-openbank-mcp

请通过 SECURITY.md 私下报告漏洞。

开发

git clone https://github.com/thatskiff33/nz-openbank-mcp.git
cd nz-openbank-mcp
uv sync --extra dev
uv run pytest                 # 100% line and branch coverage is required
uv run ruff check . && uv run mypy src
FASTMCP_ENV_FILE=/dev/null uv run fastmcp dev src/nz_openbank_mcp/server.py

要在 Claude Code 中使用本地检出版本：

claude mcp add nz-openbank --scope user \
  --env AKAHU_APP_TOKEN=app_token_... --env AKAHU_USER_TOKEN=user_token_... \
  -- uv --directory "$(pwd)" run nz-openbank-mcp

宿主插件清单为自动生成。编辑 plugin/plugin.base.toml，然后运行 uv run --no-project python scripts/sync_plugin_manifests.py。发布流程见 PUBLISHING.md；更多运维指南见 docs/。

欢迎贡献：请参阅 CONTRIBUTING.md、行为准则和变更日志。如有问题，请在 Discussions 中提问。

许可证和免责声明

本项目采用 Apache-2.0 许可证；详见 LICENSE。 本项目基于 severity1 的 nz-akahu-mcp（Apache-2.0）开发，并经过了大量修改；详见 NOTICE。 感谢 severity1 构建并开源了原始项目，没有它就不会有本项目。

本软件按原样提供。你需自行负责如何将其用于你的金融数据。维护者对因使用本软件而导致的数据丢失、未经授权的访问或财务损失概不负责。