Banktivity Swift MCP

银行业务swift mcp

Swift库， 主控程序 服务器和CLI 银行活动 个人财务档案。提供对以下内容的完全读/写访问权限 .bank8 保管库——账户、交易、类别、标签、模板、导入规则、计划交易、报表、证券和RDF导出。

• 银行Lib --具有核心数据存储库和RDF导出的纯域库，没有服务器依赖关系
• 银行活动mcp --MCP服务器通过stdio为Claude等人工智能助手提供64个工具
• 银行活动cli --用于脚本编写和自动化的独立CLI

灵感源自 银行活动mcp （TypeScript/Node.js），这是Swift中的一次彻底重写。原始用途 better-sqlite3 直接读写Core Data的SQLite存储，绕过Core Data的内部更改跟踪。这适用于读取，但直接的SQL写入对CloudKit同步是不可见的——Banktivity不知道数据发生了变化，保管库可能会损坏或无法同步。此Swift版本使用 NSPersistentContainer 因此，所有突变都通过核心数据的API，确保正确的更改跟踪和CloudKit兼容性。

警告：此服务器可以修改您的银行活动数据。 编写工具（创建、更新、删除）对您的 .bank8 拱顶。虽然服务器使用核心数据进行适当的更改跟踪，并包括一个写保护，可以在Banktivity打开时阻止突变，但人工智能助手可能会犯错误。 定期备份您的保险库 并考虑制作一份副本，直到你对自己的工作流程充满信心。作者不对任何数据丢失或损坏负责。

需求

• macOS 14+
• 银行活动 .bank8 vault文件

安装

自制（推荐）

brew install sflinter/tap/banktivity-swift-mcp

这将同时安装 banktivity-mcp 和 banktivity-cli 作为通用二进制文件（苹果硅+英特尔）。

下载二进制文件

从下载通用二进制文件 ，提取并移动到PATH：

tar xzf banktivity-swift-mcp-v0.8.0-macos-universal.tar.gz
mv banktivity-mcp banktivity-cli ~/.local/bin/

从源代码构建

需要Xcode 16+（Swift测试和通用二进制构建所需）：

git clone https://github.com/sflinter/banktivity-swift-mcp.git
cd banktivity-swift-mcp
make install        # Build universal binary and install to ~/.local/bin

其他Makefile目标：

make build          # Debug build
make test           # Run all tests
make release        # Universal release build (arm64 + x86_64)
make package        # Build release tarball with SHA256
make clean          # Remove build artifacts

配置

克劳德代码

添加到MCP设置(~/.claude/settings.json 或项目 .mcp.json):

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

克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

可用工具

账户

• list_accounts --列出所有有余额的账户
• get_account_balance --获取特定账户的余额
• get_net_worth --计算总净值
• get_spending_by_category --按日期范围分类的支出明细
• get_income_by_category --按日期范围分类的收入明细
• get_summary --总体财务摘要

交易

• get_transactions --列出具有过滤和分页功能的交易记录
• search_transactions --在收款人、备忘录等中进行全文搜索。
• get_transaction --按ID获取单笔交易
• create_transaction --创建新交易
• update_transaction --更新现有交易
• delete_transaction --删除交易

系列商品

• get_line_item --获取特定的行项目
• add_line_item --在交易中添加行项目（用于拆分）
• update_line_item --更新行项目
• delete_line_item --删除行项目

类别

• list_categories --列出所有收入/支出类别
• get_category --获取特定类别
• get_category_tree --获取完整的类别层次结构
• create_category --创建新类别

分类

• 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_statement --获取一份关于对账进展的声明
• create_statement --创建带有余额验证的新对账单
• delete_statement --删除语句并取消其行项目的对账
• reconcile_line_items --将行项目分配给语句
• unreconcile_line_items --从语句中删除行项目
• get_unreconciled_line_items --列出帐户的未对账行项目

证券

• list_securities --列出所有证券的名称、符号和货币
• create_security --使用符号、名称和货币创建新证券
• get_security_prices --获取证券的价格历史记录（按交易品种或ID，可选日期范围/限制）
• get_security_holdings --通过股票、成本基础和市场价值获取当前持有量（头寸）
• get_security_trades --获取包含股票、价格和佣金的交易历史记录（买入、卖出、转让）
• get_security_income --获得投资收益（股息、利息、资本收益分配）
• create_share_adjustment --创建股份调整（例如费用、股票分割、头寸更正）
• import_security_prices --从CSV文件（雅虎财经、OHLCV或日期/关闭）导入价格
• delete_security_prices --删除证券的价格历史记录（可选日期范围）

出口

• export_turtle --将整个vault导出为RDF/Tturtle（.ttl），也可以选择导出到文件

诊断

• dump_schema --检查核心数据模型模式（实体名称、属性、关系）

命令行界面

独立CLI(banktivity-cli)在没有MCP服务器的情况下提供相同的功能。集 BANKTIVITY_FILE_PATH 或通过 --vault:

banktivity-cli --vault ~/Documents/Banktivity/My\ Accounts.bank8 accounts list
banktivity-cli accounts balance --account-name "Checking"
banktivity-cli transactions list --account-name "Checking" --start-date 2025-01-01 --limit 10
banktivity-cli transactions create --account-name "Checking" --date 2025-06-15 --title "Coffee" --amount -4.50 --category-name "Food"
banktivity-cli tags get-by-tag --tag-name "Vacation" --limit 20
banktivity-cli tags bulk-tag --transaction-ids "100,101,102" --tag-name "Vacation"
banktivity-cli export turtle --output vault.ttl

CLI子命令

• accounts list, accounts balance, accounts net-worth, accounts spending, accounts income, accounts summary
• transactions list, transactions search, transactions get, transactions create, transactions update, transactions delete
• categories list, categories get, categories tree, categories create
• tags list, tags create, tags tag-transaction, tags get-by-tag, tags bulk-tag
• uncategorized list, uncategorized suggest, uncategorized recategorize, uncategorized bulk-recategorize, uncategorized review, uncategorized payee-summary
• line-items get, line-items add, line-items update, line-items delete
• templates list, templates get, templates create, templates update, templates delete
• import-rules list, import-rules get, import-rules match, import-rules create, import-rules update, import-rules delete
• scheduled list, scheduled get, scheduled create, scheduled update, scheduled delete
• statements list, statements get, statements create, statements delete, statements reconcile, statements unreconcile, statements unreconciled
• securities list, securities create, securities prices, securities holdings, securities trades, securities income, securities adjust, securities import-prices, securities delete-prices
• export turtle
• schema

大多数接受的命令 --account-id 也接受 --account-name 作为一种替代方案。这 transactions create 命令支持 --line-items 其中JSON数组用于多行项目（拆分）事务。

使用 --format compact 用于机器可读的单行JSON输出（默认打印效果很好）。

壳牌完井

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

克劳德代码技能

A. /banktivity 技能 可用于Claude Code。它允许Claude直接使用CLI回答有关您财务的自然语言问题——“我上个月在杂货上花了多少钱？”、“在支票中显示未分类的交易”等。

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

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

这 skills/banktivity/ 目录包含 SKILL.md 教Claude如何调用的文件 banktivity-cli 使用正确的环境变量和参数。您需要编辑 BANKTIVITY_FILE_PATH 在 SKILL.md 指向你自己的保险库。

安装后，键入 /banktivity 在任何Claude Code会话中激活它，或者当您询问交易、账户、支出或类别时，Claude会自动激活它。

安全特性

• 写防护：在任何突变之前，服务器会检查Banktivity.app是否打开了保管库（通过 lsof).如果是这样，写入将被阻止以防止损坏。
• 没有持久的历史跟踪：Banktivity使用自己的同步机制。Core Data内置的历史跟踪功能会添加无法识别的元数据，从而损坏保管库。
• 背景语境：所有写入都使用背景 NSManagedObjectContext 实例与 performAndWait 为了数据完整性。

运作原理

银行活动 .bank8 bundle是一个包含已编译核心数据模型的目录(.momd 文件）和SQLite数据库(StoreContent/core.sql).此服务器：

1. 加载并合并所有 .momd 来自vault的模型包
2. 通过以下方式打开SQLite商店 NSPersistentContainer （无历史跟踪）
3. 通过stdio传输暴露64个MCP工具
4. 使用KVC(value(forKey:))访问实体，因为我们在运行时加载Banktivity自己的编译模型

许可证

麻省理工学院