Banktivity

banktivity-swift-mcp：面向 AI 助手的 Banktivity MCP 服务和 CLI

这是一个 Swift 库、Model Context Protocol (MCP) 服务和命令行工具，可用于处理 Banktivity 个人理财文件。它让 Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端或 AI Agent 能够读取和写入 Banktivity 10 .bank8 金库： 账户、交易、拆分、类别、收款人、标签、模板、导入规则、定期交易、对账单和证券。它还可以将 金库导出为 RDF。

• banktivity-cli 是命令行工具，可用于脚本、运行 shell 命令的 AI Agent，以及自行查找信息。
• banktivity-mcp 是一个包含 79 个工具的 MCP 服务，Claude 等 AI 助手可以借此操作你的金库。
• BanktivityLib 是两者所基于的库，不依赖任何服务端组件。

每项更改都会通过 Core Data 写入，与 Banktivity 自身的写入方式相同，因此 Banktivity 的 iCloud/CloudKit 同步可以检测到这些编辑。请参阅 CloudKit 同步安全性：为什么使用 Core Data 而非直接操作 SQLite。

CloudKit 同步安全性：为什么使用 Core Data 而非直接操作 SQLite

.bank8 金库是一个 Core Data 存储，Banktivity 通过 CloudKit 同步它。

• 直接写入 SQLite 不会被同步检测到。 使用 SQL 写入 core.sql 的工具会绕过 Core Data 的更改跟踪。CloudKit 同步无法 检测到这些编辑，因此它们可能无法同步、被还原，或损坏金库。启发了 Swift 重写版的 Martijn Riemers 的 TypeScript banktivity-mcp 就是以这种方式构建的。
• 本工具通过 Core Data 写入。 Steve Flinter 的 Swift 重写版使用 NSPersistentContainer 打开金库，并采用 Banktivity 自己编译的数据 模型，通过 Core Data 进行每项更改，与 Banktivity 的方式相同。
• Banktivity 打开金库时会拒绝写入（通过 Swift 重写版中的 lsof 检查）。
• 此分支增加了更多防护措施。 CLI 编辑不再会被下一次同步还原；绝不会允许 Core Data 迁移（重写）Banktivity 的数据库；此外，写入防护现在在无法判断时会拒绝写入，并且会在每次写入保存的位置强制执行。请参阅 安全功能。

警告：此工具会更改你的 Banktivity 数据。 写入命令会实际更改你的 金库，而 AI 助手可能会出错。每次写入前请备份金库，并在信任你的配置之前 使用副本。作者不对数据丢失负责。

安全使用

• 每次对一个金库只运行一个 banktivity-cli 或 banktivity-mcp 进程。 写入会在单个进程内排队，但不同进程之间不会锁定文件。
• 在 Banktivity.app 中打开同一个金库前，请先退出所有 banktivity-mcp 服务。该应用和本工具不得同时打开此文件。 （Banktivity 打开金库时会拒绝写入，但不会拒绝读取。）
• 每次写入前都要备份。
• 在 Banktivity 10 中恢复、导入或迁移金库后，请重新查询账户、交易、对账单和类别 ID。Banktivity 可能会重新编号。

关于此分支

这是 david00769 维护的分支，源自 Steve Flinter 的 banktivity-swift-mcp。此分支 包含上游的所有功能。下文的修复和功能已通过 拉取请求 提交给上游，但自 2026 年 5 月以来，上游尚未合并任何内容。

此分支新增内容：

• 同步后仍能保留的编辑。 通过 CLI 所做的更改，在 Banktivity 下次同步时不再被还原。
• 对账单： 对账，以及用于修复对账单行的命令。
• 投资： 创建证券交易和收入，并查看每个批次已实现的资本利得。
• 安全性与报告： 只读模式、可供机器读取的命令写入情况列表、以一种报告货币显示的净资产，以及持仓市值。
• v0.17.0 新增：
  • 防止 Core Data 重写 Banktivity 数据库的保护机制；
  • accounts update；
  • line-items source，用于显示交易背后的原始银行导入数据；
  • 创建时自动设置交易类型；
  • 可选的 HTTP 服务模式。

其中部分内容来自其他人的分支。ACKNOWLEDGEMENTS.md 会注明每项贡献，CHANGELOG.md 列出每个版本的所有变更。

应该使用哪个 Banktivity MCP？

搜索 Banktivity MCP 服务时，会看到三个相关项目：

项目	语言	写入方式	安装	状态
mhriemers/banktivity-mcp	TypeScript（npm）	将 SQL 写入 core.sql（Swift 重写项目启动时的说明）	npm	启发 Swift 重写项目的原始 TypeScript 服务
sflinter/banktivity-swift-mcp	Swift	Core Data（NSPersistentContainer）	Homebrew（sflinter/tap）	此分支基于的 Swift 重写项目
david00769/banktivity-swift-mcp（此仓库）	Swift	Core Data，以及上述保护机制	下载发行版 或 make install	正在维护；包含上游的所有功能，以及此分支的新增内容

如果你希望 AI 助手写入通过 iCloud 同步的保险库， 请使用 Core Data 项目之一。这三个项目都能读取保险库。

要求

• macOS 14 或更高版本
• Banktivity .bank8 保险库

安装

下载发行版（推荐）

每个发行版 都提供一个通用下载包（适用于 Apple Silicon 和 Intel）以及校验和文件。CI 会从已标记的提交构建并测试发行版。以 v0.17.3 为例：

base=https://github.com/david00769/banktivity-swift-mcp/releases/download/v0.17.3
curl -LO "$base/banktivity-swift-mcp-v0.17.3-macos-universal.tar.gz"
curl -LO "$base/banktivity-swift-mcp-v0.17.3-macos-universal.tar.gz.sha256"
shasum -a 256 -c banktivity-swift-mcp-v0.17.3-macos-universal.tar.gz.sha256   # prints "OK"

tar xzf banktivity-swift-mcp-v0.17.3-macos-universal.tar.gz
xattr -d com.apple.quarantine banktivity-cli banktivity-mcp 2>/dev/null || true
mkdir -p ~/.local/bin && mv banktivity-cli banktivity-mcp ~/.local/bin/
banktivity-cli --version   # 0.17.3

二进制文件采用临时签名，未经公证。xattr 命令会移除 macOS 添加到下载文件上的隔离标记，否则这些文件将无法运行。

Claude Desktop 扩展（.mcpb）

每个发行版还包含 banktivity-swift-mcp-vX.Y.Z-macos-universal.mcpb，这是一个 MCP Bundle。下载后用 Claude Desktop 打开，即可将 banktivity-mcp 安装为扩展。将保险库路径留空，即可使用 Banktivity 10 保险库（参见 我的保险库在哪里？），并可考虑开启只读模式。扩展内的二进制文件采用临时签名，未经 公证；如果 macOS 拒绝运行，请使用 xattr -dr com.apple.quarantine ~/Library/Application\ Support/Claude/Claude\ Extensions 清除隔离标记，然后重启 Claude Desktop。此安装方式只安装 MCP 服务；如需 CLI，请使用上方的下载包。该服务 也已列入 MCP Registry，名称为 io.github.david00769/banktivity-swift-mcp。

从源代码构建

建议使用 Xcode 16 或更高版本。没有 Xcode 时，Makefile 会回退到使用 Command Line Tools 进行构建和安装（此处未经测试）；运行测试则需要 Xcode。

git clone https://github.com/david00769/banktivity-swift-mcp.git
cd banktivity-swift-mcp
make install        # universal build, installed to ~/.local/bin

始终使用 make install（或使用 make install-fast 进行更快的单架构构建）安装。切勿使用 cp 将新二进制文件复制到 ~/.local/bin 覆盖旧文件。cp 会原地重写文件，而仍在运行的 banktivity-mcp 下次启动时会被 macOS 终止（“Code Signature Invalid”）。Makefile 会先复制到临时名称、为其签名，然后再将其重命名到目标位置。

Makefile 的其他目标：

make help           # list all targets
make install-fast   # native-architecture build and install, for development
make verify         # check that the installed binaries actually run
make build          # debug build
make test           # run all tests
make test-filter FILTER=AccountUpdateTests   # run one test type
make release        # universal release build (arm64 + x86_64)
make package        # release tarball plus its SHA-256
make mcpb           # the tarball plus the Claude Desktop bundle (.mcpb)
make clean          # remove build output

make test 会以与发布构建相同的方式运行测试套件：使用发布配置、单个工作进程和 Xcode 的测试框架。

Homebrew（上游版本）

brew install sflinter/tap/banktivity-swift-mcp

此操作会安装上游的二进制文件，不包含此分支的更改。

如何制作发布版本

CI（.github/workflows/ci.yml）会在每次向 main 推送以及每次针对 main 的拉取请求中运行。它会先运行 make test，再运行 make package，因此任何会导致发布构建失败的更改，都会在有人创建标签前被发现。要发布版本，请更新 Sources/BanktivityLib/Version.swift 中的版本号，并在 CHANGELOG.md 中添加对应的部分，然后推送一个标签：

git tag -a v0.18.0 -m "v0.18.0" && git push origin v0.18.0

随后，.github/workflows/release.yml 会检查标签是否与 Version.swift 中的版本匹配，运行测试、构建 tarball 并发布版本。CHANGELOG 中的部分会成为发布说明。

配置

我的保险库在哪里？

Banktivity 10 会将通过 Banktivity Cloud 同步的保险库存放在自己的资源库中，而不是 Documents 中：

~/Library/Group Containers/group.com.iggsoftware.banktivity.library/IGGFinance/production/Documents/<vault id>/1.bank8

<vault id> 文件夹会因 Mac 而异。如果未设置 BANKTIVITY_FILE_PATH 或其值为空，banktivity-mcp 和 banktivity-cli 就会使用该文件夹中的保险库，前提是其中恰好只有一个。如果有多个，它们会列出这些保险库并停止，以便你选择一个。

**macOS 会先请求权限。**该文件夹属于 Banktivity，而 macOS 会保护一个应用的数据不被其他应用访问，因此首次运行会被阻止，直到你授予访问权限。请参阅在 macOS 上授予访问权限。

保存在其他位置的保险库（以下示例使用 ~/Documents/Banktivity/My Accounts.bank8）需要设置路径。路径必须以 .bank8 结尾；如果你提供的是文件夹，错误信息会列出其中的保险库。

在 macOS 上授予访问权限

macOS 会阻止其他程序读取 Banktivity 10 的资料库，除非你授予访问权限。在此之前，服务日志会显示：

Error: macOS blocked access to Banktivity's library (…/IGGFinance/production/Documents). …

而 Claude Desktop 会将扩展显示为失败。你也可能会收到 macOS 通知，提示某个程序正在访问“来自其他应用的数据”。修复方法如下：

1. 退出 Banktivity。
2. 打开 系统设置 > 隐私与安全性 > 完全磁盘访问权限，然后点击列表下方的 +。
3. 按 ⌘⇧G，粘贴当前实际运行的 banktivity-mcp 路径，然后点击 打开：
   • Claude Desktop 扩展： ~/Library/Application Support/Claude/Claude Extensions/local.mcpb.david00769.banktivity-swift-mcp/server/banktivity-mcp
   • 从发行版安装或使用 make install 安装：~/.local/bin/banktivity-mcp （CLI 还需要添加 ~/.local/bin/banktivity-cli）
4. 确认 banktivity-mcp 现在显示在列表中，且开关已打开。
5. 重启服务。在 Claude Desktop 中，前往“设置”>“扩展”，关闭再开启 Banktivity（或退出并重新打开 Claude Desktop）。

**授予程序本身权限，而不是运行它的应用权限。**为 Claude.app 授予完全磁盘访问权限无法解锁该扩展；添加 banktivity-mcp 二进制文件则可以。Claude.app 不需要完全磁盘访问权限。例外情况是已获得完全磁盘访问权限的终端（Terminal、iTerm）：从中运行的 CLI（包括通过 Claude Code 运行）无需单独添加。

**每次更新后都要重新授予权限。**这些二进制文件使用临时签名，而非公证签名，因此 macOS 会将权限绑定到确切的文件。更新会安装新文件，所以需要重新添加（先移除旧条目）。

**如何确认已生效。**Claude Desktop 的服务日志 ~/Library/Logs/Claude/mcp-server-Banktivity.log 会显示：

Vault: /Users/you/Library/Group Containers/…/IGGFinance/production/Documents/<vault id>/1.bank8
Core Data container loaded successfully

在扩展的 配置 对话框中，开启 只读 并点击 保存，直到你信任自己的设置。切换开关只有在保存后才会生效。

Claude Code

将以下内容添加到项目的 .mcp.json，或添加到 ~/.claude.json 以应用于所有项目 （claude mcp add 会写入相同条目）：

{
  "mcpServers": {
    "banktivity": {
      "command": "/Users/you/.local/bin/banktivity-mcp",
      "env": {
        "BANKTIVITY_FILE_PATH": "/Users/you/Documents/Banktivity/My Accounts.bank8"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

将相同的代码块添加到 ~/Library/Application Support/Claude/claude_desktop_config.json，然后 重启 Claude Desktop。

Cursor（mcp.json）

将相同的代码块添加到 ~/.cursor/mcp.json，或添加到项目中的 .cursor/mcp.json。

其他 MCP 客户端

任何能够启动 stdio MCP 服务的客户端都需要相同的两项配置：命令 banktivity-mcp（使用其绝对路径），以及将环境变量 BANKTIVITY_FILE_PATH 设置为你的 .bank8 资料库（Banktivity 10 资料库可选；请参阅我的资料库在哪里？）。若要通过 HTTP 使用一个共享服务，请参阅下文。对于能够运行 Shell 命令的 Agent，也可以考虑使用 CLI。

通过 HTTP 运行一个长期运行的服务

通常，每个客户端都会通过 stdio 启动自己的 banktivity-mcp。如果你更愿意运行一个持续工作的服务（例如通过 launchd），请设置 BANKTIVITY_HTTP_PORT。它只会监听 127.0.0.1：

BANKTIVITY_FILE_PATH=~/Documents/Banktivity/My\ Accounts.bank8 \
BANKTIVITY_HTTP_PORT=8790 banktivity-mcp
# Banktivity MCP server listening on http://127.0.0.1:8790/mcp

BANKTIVITY_HTTP_PATH 可以更改 /mcp 路径。检查服务是否响应：

curl -s http://127.0.0.1:8790/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}'
# {"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{...}},"serverInfo":{"name":"banktivity-mcp","version":"0.17.3"},...}}

客户端使用 URL 而非命令连接：

{ "mcpServers": { "banktivity": { "type": "http", "url": "http://127.0.0.1:8790/mcp" } } }

使用前请注意以下两点：

• **Mac 上的任何程序都可以连接。**这里没有密码，因此请像保护资料库文件一样保护此端口。来自其他网站的浏览器页面会被拒绝（系统会检查其 Origin 标头），格式错误的请求也会被拒绝。
• **服务运行时会一直打开资料库，且无法看到 Banktivity 所做的更改。**在 Banktivity 中打开资料库之前，请停止服务；之后再重新启动。

只读模式

将 BANKTIVITY_STORE_READ_ONLY=1（或 true、yes）设为只读模式打开保险库。即使只是读取，SQLite 也会整理其预写日志，从而修改磁盘上的文件。若要查看保险库且不改动其中任何字节，请使用此模式：

BANKTIVITY_STORE_READ_ONLY=1 \
  banktivity-cli accounts list --vault ~/Documents/Banktivity/My\ Accounts.bank8

在此模式下，写入操作到达数据库时会失败。SQLite 仍可能自行以写入方式打开 core.sql-shm，因此这只是额外的一层保护；请保留备份。

以单一货币表示的净资产和持仓价值

净资产（accounts net-worth、get_net_worth 以及 summary 中的 netWorth）会报告 assets、liabilities 和 netWorth，其中各账户的现金按其自身货币计入，不进行换算。净资产还会报告：

• reportingCurrency 和 converted：换算为单一货币后的相同总额，以及 holdingsValue（投资的市值）和 netWorthWithHoldings；
• currencyBreakdown：按货币列出现金、持仓、所用汇率和换算后的金额；
• warnings：例如，因保险库中没有某种货币的汇率而被排除的账户。

使用 BANKTIVITY_REPORTING_CURRENCY 选择货币（例如 ISO 代码 USD）。如果未设置，则使用 EUR，也就是这些总额一贯使用的标示货币。汇率取自保险库自身的汇率表：若有直接汇率，则使用最新的直接汇率；否则使用最新反向汇率的倒数；再否则通过 USD 换算。

BANKTIVITY_REPORTING_CURRENCY=USD banktivity-cli accounts net-worth

accounts list 和 accounts balance（及其 MCP 工具）中的投资账户也会包含 holdingsValue：持有的份额 × 最新收盘价 × 证券的价格乘数。它会与 balance 一同显示，但不会计入其中。

可用工具

账户

• list_accounts — 列出所有账户及其余额
• get_account_balance — 获取指定账户的余额
• get_net_worth — 计算净资产总额
• get_spending_by_category — 按类别统计指定日期范围内的支出
• get_income_by_category — 按类别统计指定日期范围内的收入
• get_summary — 获取整体财务摘要
• update_account — 重命名账户、更改账户类型或隐藏账户（参见更改账户）

交易

• get_transactions — 列出交易，支持筛选和分页
• search_transactions — 在收款方、备注等内容中进行全文搜索
• get_transaction — 按 ID 获取单笔交易
• create_transaction — 创建新交易；可选指定 transaction_type，否则根据银行账户分录推断其为存款、取款或转账
• repair_forex_transfer — 使用目标货币收款和源货币费用拆分修复现有的跨货币转账
• update_transaction — 更新现有交易
• delete_transaction — 删除交易

跨币种转账修复

repair_forex_transfer 通过 MCP 修复现有的跨币种转账交易；CLI 中也提供相同的 BanktivityLib 修复路径，命令为 transactions repair-forex。当 Banktivity 中已经存在转账，但记录的源金额和目标金额数值相同，或没有单独记录费用时，可使用此功能。它不会创建新转账。

必填输入：

• transaction_id — 要修复的现有交易
• source_account_id — 以源货币扣款的账户
• target_account_id — 接收资金的目标货币账户
• fee_category_id — 用于记录源货币费用的支出类别
• gross_source_amount — 源货币的扣款总额
• source_fee_amount — 以源货币计的费用
• target_amount — 目标账户收到的金额
• exchange_rate — 扣除费用后的源金额兑换为目标货币的汇率

可选输入包括 title、date、note、source_memo、target_memo 和 fee_memo。

修复后的交易以源账户货币存储。目标行项目将 gross_source_amount - source_fee_amount 存为其交易金额，将 exchange_rate 存为 pExchangeRate，并将 target_amount 存为目标账户金额。若交易包含未由工具管理的额外行项目，系统会拒绝修复，而不会合并或删除这些项目。

MCP 调用参数示例：

{
  "transaction_id": 1001,
  "source_account_id": 2001,
  "target_account_id": 2002,
  "fee_category_id": 3001,
  "gross_source_amount": 100.00,
  "source_fee_amount": 1.00,
  "target_amount": 74.25,
  "exchange_rate": 0.75,
  "title": "Cross-Currency Transfer",
  "date": "2025-04-27",
  "note": "Provider transfer reference",
  "source_memo": "Source-currency gross debit",
  "target_memo": "Target-currency receipt",
  "fee_memo": "Provider fee"
}

对应的 CLI 示例：

banktivity-cli transactions repair-forex \
  --transaction-id 1001 \
  --source-account-id 2001 \
  --target-account-id 2002 \
  --fee-category-id 3001 \
  --gross-source-amount 100.00 \
  --source-fee-amount 1.00 \
  --target-amount 74.25 \
  --exchange-rate 0.75 \
  --title "Cross-Currency Transfer" \
  --date 2025-04-27 \
  --note "Provider transfer reference" \
  --source-memo "Source-currency gross debit" \
  --target-memo "Target-currency receipt" \
  --fee-memo "Provider fee"

行项目

• get_line_item — 获取指定行项目
• get_line_item_source — 获取行项目的原始导入银行详情（Plaid/OFX 描述、来源类型和标识符）；手动录入的项目为空
• add_line_item — 为交易添加行项目（用于拆分）
• update_line_item — 更新行项目
• delete_line_item — 删除行项目

类别

• list_categories — 列出所有收入/支出类别
• get_category — 获取指定类别
• get_category_tree — 获取完整的类别层级结构
• create_category — 创建新类别
• audit_category_entities — 查找存储在错误内部类型下的类别；旧工具可能会遗留此类问题

分类

• get_uncategorized_transactions — 查找未分类的交易
• suggest_category_for_merchant — 根据商家历史记录建议类别
• recategorize_transaction — 更改交易的类别
• bulk_recategorize_by_payee — 重新分类某收款方的所有交易
• review_categorizations — 查看近期的分类更改
• get_payee_category_summary — 汇总每个收款方使用的类别

标签

• get_tags — 列出所有标签
• create_tag — 创建新标签
• tag_transaction — 为交易添加标签
• get_transactions_by_tag — 查找带有指定标签的交易
• bulk_tag_transactions — 一次为多笔交易添加标签

模板

• list_transaction_templates — 列出已保存的交易模板
• get_transaction_template — 获取指定模板
• create_transaction_template — 创建新模板
• update_transaction_template — 更新模板
• delete_transaction_template — 删除模板

导入规则

• list_import_rules — 列出所有导入规则
• get_import_rule — 获取指定导入规则
• match_import_rules — 查找与收款方字符串匹配的规则
• create_import_rule — 创建新导入规则
• update_import_rule — 更新导入规则
• delete_import_rule — 删除导入规则

计划交易

• list_scheduled_transactions — 列出所有计划交易
• get_scheduled_transaction — 获取指定计划交易
• create_scheduled_transaction — 创建新的计划交易
• update_scheduled_transaction — 更新计划交易
• delete_scheduled_transaction — 删除计划交易

对账单（对账）

• list_statements — 列出账户的对账单
• get_account_reconciliation_status — 获取账户的对账单数量和最新对账单结束日期
• get_statement — 获取对账单及其对账进度
• create_statement — 创建对账单并验证余额
• delete_statement — 删除对账单并取消其明细项目的对账；内部／未命名的投资行需要明确设置 allow_internal
• reconcile_line_items — 将明细项目分配给对账单
• unreconcile_line_items — 从对账单中移除明细项目
• get_unreconciled_line_items — 列出账户中尚未对账的明细项目
• update_statement — 更正对账单的期末余额，使其与 Banktivity 窗口显示的金额一致
• plan_statement_visible_row_correction — 根据你从 Banktivity 对账单窗口读取的起始金额、结束金额和缺失金额生成更正计划（它不会自行读取 Banktivity 屏幕）

对账单中的每个明细项目都包含 statementBalanceAmount，即该项目计入对账单余额的金额。对于投资账户，请累加 statementBalanceAmount，而不是 amount 或 accountAmount：证券交易可能会改变现金余额，而原始金额并未体现这一点。

证券

• list_securities — 列出所有证券的名称、代码和货币
• create_security — 使用代码、名称和货币创建新证券
• get_security_prices — 获取证券的价格历史记录（按代码或 ID，可选日期范围／数量上限）
• get_security_holdings — 获取当前持仓，包括股数、成本基础和市值
• get_security_trades — 获取交易历史记录（买入、卖出、转入），包括股数、价格和佣金
• get_security_realized_gains — 获取每笔已平仓批次的已实现资本利得（购入日期、所得款项、成本基础、收益、短期／长期）
• get_security_income — 获取投资收入（股息、利息、资本利得分配）
• create_security_trade — 记录买入或卖出（正股数表示买入，负股数表示卖出），并创建对应的现金明细
• update_security_trade — 更改现有交易的股数、价格、金额、佣金或证券
• create_security_income — 创建原生证券收入，目前支持股息收入
• rename_security — 更改证券代码、名称或两者（如果已有其他证券使用该代码，则拒绝更改）
• create_share_adjustment — 创建股数调整（例如收费、股票拆分、持仓更正）
• import_security_prices — 从 CSV 文件导入价格（Yahoo Finance、OHLCV 或 Date/Close）
• delete_security_prices — 删除证券的价格历史记录（可选日期范围）
• delete_security — 删除没有任何交易引用的证券记录

导出

• export_turtle — 将整个保险库导出为 RDF/Turtle（.ttl），可选择导出到文件

诊断

• dump_schema — 检查 Core Data 模型架构（实体名称、属性、关系）
• get_capabilities — 列出所有命令和工具、它们是读取还是写入，以及所需的确认方式

CLI 或 MCP 服务：选择运行方式，并确保保险库安全

CLI 是本项目的一等组成部分，原因在于保险库的安全性。

MCP 服务会持续运行。 banktivity-mcp 启动时会打开保险库，并一直保持打开状态，直到退出。Claude Desktop 等客户端通常会在启动时运行它，并让它在后台持续运行，即使你没有在使用它。如果此时 Banktivity 也打开同一个保险库进行读写，或者其同步操作访问了该文件，两个进程就会同时打开数据库。Banktivity 可能会卡住或崩溃，同步也可能出错。你可以在用完后退出服务，但很容易忘记。

CLI 会为单条命令打开保险库，然后退出。 banktivity-cli 会加载保险库、执行读取或写入、输出 JSON，然后退出，因此你打开 Banktivity 时，它不会占用该文件。AI Agent 擅长通过 shell 调用工具，因此 Claude Code、Cursor 的 Agent 以及其他终端 Agent 可以通过 CLI 完成与调用 MCP 工具相同的工作。Claude Code 技能正是这样做的。

	banktivity-cli	banktivity-mcp
保持保险库打开的时间	仅在运行单条命令期间	服务运行期间
适用场景	Claude Code、终端 Agent、脚本、cron	只支持 MCP 的客户端（例如 Claude Desktop）
打开 Banktivity 前	无需操作	退出服务（或启动该服务的客户端）

两种工具都无法做到以下事情：

• 两者都不会锁定保险库。 当 Banktivity 打开保险库时，两者都会拒绝写入（写入前会检查 lsof，结果缓存 3 秒）。没有任何机制会阻止 Banktivity 在命令运行期间打开保险库，也不会阻止读取操作。CLI 缩短了冲突窗口，但并未消除它。
• 两者都不能替代备份。 开始任何写入操作前，请先备份保险库。

# Read the five latest transactions; nothing stays running afterwards
banktivity-cli transactions list --vault ~/Documents/Banktivity/My\ Accounts.bank8 --limit 5

CLI

独立的 CLI（banktivity-cli）无需 MCP 服务，即可提供相同的查询和写入功能。它会读取通过 --vault /absolute/path/to/Ledger.bank8 或 BANKTIVITY_FILE_PATH 选择的 .bank8 保险库；如果两者都未指定，则读取 Banktivity 10 的保险库（我的保险库在哪里？）。

首先查看内置帮助：

banktivity-cli --help
banktivity-cli accounts --help
banktivity-cli statements inspect-membership --help
banktivity-cli capabilities --format compact

运行帮助命令无需打开保险库，因此是安全的。读取命令会将 JSON 输出到标准输出。写入命令会通过 Core Data 立即更改财务记录；使用前请先备份保险库，并查看相应命令的安全措施。

常见示例：

banktivity-cli accounts list --vault ~/Documents/Banktivity/My\ Accounts.bank8
banktivity-cli accounts balance --account-name "Checking"
banktivity-cli transactions list --account-name "Checking" --start-date 2025-01-01 --limit 10
banktivity-cli statements status --account-name "Brokerage"
banktivity-cli tags get-by-tag --tag-name "Vacation" --limit 20
banktivity-cli export turtle --output vault.ttl

CLI 操作示例

以下是常见任务的可复制粘贴命令。只需设置一次 BANKTIVITY_FILE_PATH，或者在子命令后添加 --vault <path>（例如 accounts list --vault <path>；不能在子命令前使用）。每条命令都支持 --format compact，可输出单行 JSON，便于脚本和 Agent 解析。

export BANKTIVITY_FILE_PATH=~/Documents/Banktivity/My\ Accounts.bank8

# Split one payment across two categories. Make the lines balance:
# money out of Checking (-120) equals money into the categories (+90, +30).
# Any difference is added as an uncategorized offset line.
banktivity-cli transactions create --date 2026-10-01 --title "Costco" \
  --line-items '[{"account_name":"Checking","amount":-120},
                 {"account_name":"Groceries","amount":90,"memo":"food"},
                 {"account_name":"Household","amount":30}]'

# A simple two-line transaction with an explicit type. The category line
# gets the opposite amount (+50).
banktivity-cli transactions create --account-name "Checking" --date 2026-10-02 \
  --title "Cafe" --amount -50 --category-name "Dining" --transaction-type withdrawal

# Full-text search across payees and memos, as one-line JSON
banktivity-cli transactions search --format compact --query "Amazon" --limit 20

# Uncategorized transactions in one account, including transfers
banktivity-cli uncategorized list --account-id 3 --limit 50 --no-exclude-transfers

# Which commands write, so an agent can stick to reads
banktivity-cli capabilities --format compact

# Open the vault read-only (see Read-only mode for what this does not cover)
BANKTIVITY_STORE_READ_ONLY=1 banktivity-cli accounts list

transactions create 选项：

选项	含义
--account-id / --account-name	第一条明细所用的账户（简单模式）
--date	交易日期，格式为 YYYY-MM-DD（必填）
--title	收款方或标题（必填）
--amount	账户明细的金额；除非提供 --line-items，否则必填
--category-id / --category-name	第二条明细所用的类别，其金额为 -amount
--note	可选备注
--transaction-type	check、deposit、transfer 或 withdrawal；省略时自动推断
--line-items	JSON 数组，包含 {"account_id" or "account_name", "amount", "memo"?}；用于替代账户、金额和类别选项

更改账户

accounts update 用于重命名账户、更改账户类型或隐藏账户：

banktivity-cli accounts update --account-name "Old Checking" --name "Joint Checking"
banktivity-cli accounts update --account-id 12 --type savings   # checking to savings: fine
banktivity-cli accounts update --account-id 12 --hidden         # --no-hidden shows it again

新类型必须与原类型处于投资分界线的同一侧。支票账户可以改为储蓄账户或信用卡账户，529 账户可以改为 401k。但支票账户不能改为经纪账户，因为 Banktivity 只会在投资账户中保存证券：

$ banktivity-cli accounts update --account-id 12 --type investment
Error: [validation_failed] Account 12 cannot move between investment and non-investment types (class 1001 to 2000); create a new account instead

允许在资产类型和负债类型之间切换（例如将支票账户改为信用卡账户），这会将余额移至净资产的另一侧。 accounts update --help 会列出所有类型名称；accounts create --type 接受相同的名称。类别则通过类别命令更改。

查看银行发送的内容

line-items source 会显示导入交易背后的原始记录，也就是 Banktivity 重命名收款方或应用导入规则之前的数据：

$ banktivity-cli line-items source 4821
[
  {
    "amount" : -4.5,
    "date" : "2026-10-01",
    "details" : "SQ *BLUE BOTTLE COFFEE 0123",
    "matched" : true,
    "sourceIdentifier" : "pl_8Vd45zonEXAMPLE",
    "sourceTime" : "2026-10-02T09:53:14Z",
    "sourceType" : "plaid"
  }
]

手动录入的交易会返回 []。

创建时的交易类型

以前，transactions create 会将每笔新交易设为数据库恰好最先返回的类型，通常是“Return Of Capital”。现在，它会根据银行和信用卡行项目确定类型：

行项目	类型
两个或更多不同的银行或信用卡账户	转账
一个账户，资金流出	取款
一个账户，资金流入	存款

$ banktivity-cli transactions create --date 2026-10-02 --title "Move to savings" \
    --line-items '[{"account_id":6,"amount":-500},{"account_id":7,"amount":500}]'
{ "id" : 23122, "title" : "Move to savings", "transactionType" : "Transfer", ... }

要自行选择类型，请传入 --transaction-type，并指定 check、deposit、transfer 或 withdrawal。买入、股息等投资行项目需要关联证券，因此请使用 securities create-trade 和 securities create-income 创建。transactions update --transaction-type 仍可为现有交易设置任意类型。

命令参考

以下命令组构成完整的 CLI 命令集。使用命令组的 --help 输出查看必需参数、默认值和写入确认要求。

• accounts：list、balance、net-worth、spending、income、summary、create、update
• transactions：list、search、get、create、repair-forex、update、delete、sync-info
• categories：list、get、tree、audit-entities、create
• tags：list、create、tag-transaction、get-by-tag、bulk-tag
• uncategorized：list、suggest、review、payee-summary、recategorize、bulk-recategorize
• line-items：get、source、add、update、delete
• templates：list、get、create、update、delete
• import-rules：list、get、match、create、update、delete
• scheduled：list、get、create、update、delete
• statements：list、status、get、inspect-membership、inspect-sync-record、replace-internal-row-with-visible-statement、restore-internal-row-from-preimage、visible-row-correction-plan、create、update、delete、reconcile、unreconcile、unreconciled
• securities：list、create、rename、delete、prices、import-prices、delete-prices、fix-prices、holdings、trades、realized-gains、income、create-trade、create-income、link-income-category、adjust、update-trade
• reconciliation：execute-bundle 运行经过审核的 JSON 修复计划，并依据 SHA-256 摘要进行校验
• export：turtle
• schema：导出 Core Data 架构
• capabilities：列出所有命令和工具、它们是否会写入，以及所需的确认方式

重要行为：

• 接受 --account-id 的命令通常也接受 --account-name。
• 对账单日期以本地时区的整天为单位。对某个条目进行对账或取消对账时，其已清算标记会保持原样。
• transactions create --line-items 接受用于拆分交易的 JSON 数组。有关如何选择交易类型，请参阅创建时的交易类型。
• statements inspect-membership 和 statements inspect-sync-record 仅执行读取操作。它们会显示哪些条目属于某张对账单，以及该对账单的同步状态，且绝不会创建缺失的记录。
• 替换或恢复内部对账单行需要准确的账户、期间、成员条目、已清算状态，以及该行原始状态的 SHA-256 快照。这些命令只修复专为其设计的情形。
• reconciliation execute-bundle 会校验计划摘要、保险库、操作顺序和每条命令，然后才运行任何内容。
• capabilities 会以 JSON 格式列出所有命令和工具：它们是否会写入、需要哪些确认标志，以及是否支持试运行。

脚本需要单行 JSON 时，请使用 --format compact；默认输出为便于人工查看的格式化 JSON。

Shell 补全

ArgumentParser 会自动提供 Shell 补全脚本：

banktivity-cli --generate-completion-script bash   # Bash completions
banktivity-cli --generate-completion-script zsh    # Zsh completions
banktivity-cli --generate-completion-script fish   # Fish completions

例如，安装 Zsh 补全：

banktivity-cli --generate-completion-script zsh > ~/.zfunc/_banktivity-cli

Claude Code 技能

Claude Code 可使用 /banktivity 技能。借助该技能，Claude 可以直接使用 CLI，以自然语言回答有关你财务状况的问题，例如“上个月我在杂货上花了多少钱？”“显示 Checking 账户中的未分类交易”等。

安装时，将技能目录复制到 Claude Code 的全局配置中：

mkdir -p ~/.claude/skills
cp -r skills/banktivity ~/.claude/skills/banktivity

skills/banktivity/ 目录包含 SKILL.md 文件，其中说明了如何使用正确的环境变量和参数调用 banktivity-cli。你需要编辑 SKILL.md 中的 BANKTIVITY_FILE_PATH，使其指向你自己的保险库。

安装后，在任意 Claude Code 会话中输入 /banktivity 即可启用该技能；当你询问交易、账户、支出或类别相关问题时，Claude 也会自动启用它。

安全功能

• 写入保护：在进行任何修改之前，服务会检查 Banktivity.app 是否已打开该保险库（通过 lsof）。如果已打开，则会阻止写入，以防止数据损坏。
• 不进行架构迁移：Core Data 的自动迁移已关闭。如果从保险库读取的数据模型与其数据库不匹配，工具会拒绝打开。若启用此功能，Core Data 会通过删除并重新创建表来“迁移”；曾有一位用户因此丢失了 40,459 条价格记录。
• 不启用持久化历史记录：Banktivity 使用自己的同步机制。Core Data 内置的历史记录功能会添加无法识别的元数据，从而损坏保险库。
• 后台上下文：所有写入都使用后台 NSManagedObjectContext 实例，并通过 performAndWait 确保数据完整性。
• 保险库保持打开的时长：banktivity-mcp 会在运行期间一直保持保险库打开；banktivity-cli 仅在单条命令运行期间保持打开。两者都不会锁定文件。请参阅命令行工具还是 MCP 服务。

工作原理

Banktivity 的 .bank8 软件包是一个文件夹，其中包含 Banktivity 编译后的数据模型（.momd 文件）和 SQLite 数据库（StoreContent/core.sql）。此工具会：

1. 按文件名顺序加载并合并保险库中的所有 .momd 模型软件包
2. 通过 NSPersistentContainer 打开 SQLite 存储（不启用历史记录跟踪，也不进行迁移）
3. 通过标准输入输出公开 79 个 MCP 工具；设置 BANKTIVITY_HTTP_PORT 后，则通过环回 HTTP 公开
4. 使用 KVC（value(forKey:)）访问实体，因为我们会在运行时加载 Banktivity 自己编译的模型

常见问题

Claude（或 Cursor，或其他 AI Agent）能读取我的 Banktivity 数据吗？ 可以。将 MCP 客户端指向 banktivity-mcp（配置）， 或者让具备 Shell 操作能力的 Agent 运行 banktivity-cli（命令行工具）。

它与 iCloud / CloudKit 同步一起使用安全吗？ 写入会像 Banktivity 自身那样通过 Core Data 进行，因此同步机制可以识别这些更改 （CloudKit 同步安全性）。 Banktivity 打开同一个保险库时不要运行此工具，并请先备份。

扩展程序提示“macOS 阻止了对 Banktivity 资料库的访问”，无法运行。 macOS 需要先获得你的授权：将 banktivity-mcp 程序本身添加到 “完全磁盘访问权限”（在 macOS 上授予访问权限）。

运行中的 MCP 服务会在我打开 Banktivity 时造成问题吗？ 有可能：服务会一直保持保险库打开。打开 Banktivity 前请先退出服务，或者使用 命令行工具（命令行工具还是 MCP 服务）。

它支持 Banktivity 10 和 .bank8 文件吗？ 支持。它会读取 .bank8 软件包中的 Banktivity 自身数据模型 （工作原理）。

我能否只授予 AI 只读访问权限？ 设置 BANKTIVITY_STORE_READ_ONLY=1（只读模式），并使用 banktivity-cli capabilities 查看哪些命令会进行写入。这是一个安全防护层，而非沙盒：能够运行 Shell 命令的 Agent 可以取消设置该变量，因此如果必须禁止写入，请提供保险库的副本。

致谢

此分支包含 Peter Baker、Roberto Michelena、producethis、 muxadil、Richard Jeans、Howy Perrin 和 Martijn Riemers 的贡献， 并基于 Steve Flinter 的原始项目。ACKNOWLEDGEMENTS.md 列出了每项 贡献、其来源以及采用方式。

许可证

本项目采用两种许可证；LICENSE 说明了各自适用的范围。

• MIT： 截至提交 9bcd5d2 的所有内容（该提交紧接 v0.17.2 之后），包括截至 v0.17.2 的所有版本、Steve Flinter 的原始作品以及所有注明的贡献（LICENSES/MIT.txt）。
• PolyForm Noncommercial 1.0.0： david00769 在该提交之后所做的更改（LICENSES/PolyForm-Noncommercial-1.0.0.md）。 可免费用于个人、业余爱好、研究、教育、慈善和政府用途。

对采用 PolyForm 许可证的部分进行商业使用，需要从 david00769 （[email protected]）处获取商业许可证。