Banktivity

banktivity-swift-mcp：AI アシスタント向け Banktivity MCP サーバーおよび CLI

Banktivityの個人財務ファイル向けのSwiftライブラリ、Model Context Protocol (MCP)サーバー、およびコマンドラインツールです。Claude Desktop、Claude Code、Cursor、その他のMCPクライアントやAIエージェントから、Banktivity 10の.bank8ボルトにある口座、取引、分割、カテゴリ、受取人、タグ、テンプレート、インポートルール、予定取引、明細書、有価証券の読み書きができます。また、ボルトをRDFとしてエクスポートすることもできます。

• banktivity-cliは、スクリプトやシェルコマンドを実行するAIエージェント、自分で情報を検索する場合に使うコマンドラインツールです。
• banktivity-mcpは79個のツールを備えたMCPサーバーで、ClaudeなどのAIアシスタントがボルトを操作できます。
• BanktivityLibは、両方の基盤となるライブラリです。サーバーへの依存関係はありません。

すべての変更は、Banktivity自体が書き込みを行うのと同じ方法でCore Dataを通じて行われるため、編集内容はBanktivityのiCloud／CloudKit同期に反映されます。CloudKit同期の安全性：直接SQLiteを使わずCore Dataを使う理由をご覧ください。

CloudKit同期の安全性：直接SQLiteを使わずCore Dataを使う理由

.bank8ボルトはCore Dataストアであり、BanktivityはCloudKitを通じて同期します。

• SQLiteへの直接書き込みは同期に反映されません。 SQLでcore.sqlに書き込むツールは、Core Dataの変更追跡を迂回します。CloudKit同期はこうした編集を認識しないため、同期に失敗したり、編集が元に戻ったり、ボルトが破損したりする可能性があります。Swift版への書き換えのきっかけとなったMartijn RiemersのTypeScript製banktivity-mcpは、この方式で作られていました。
• このツールはCore Data経由で書き込みます。 Steve FlinterによるSwift版への書き換えでは、Banktivity独自のコンパイル済みデータモデルを使ってNSPersistentContainerでボルトを開き、Banktivityと同じようにすべての変更を通じて行います。
• Banktivityでボルトを開いている間は書き込みを拒否します（Swift版への書き換えに由来するlsofチェック）。
• このフォークではさらに保護機能を追加しています。 CLIによる編集が次の同期で元に戻されることはなく、Core DataによるBanktivityのデータベースのマイグレーション（書き換え）は決して許可されません。また、書き込みガードは判断できない場合にも拒否し、すべての書き込みが保存される場所で適用されます。安全機能をご覧ください。

警告：このツールはBanktivityのデータを変更します。 書き込みコマンドはボルトに実際の変更を加え、AIアシスタントは誤りを犯すことがあります。書き込みを行う前にボルトをバックアップし、設定に問題がないと確信できるまではコピーを使って作業してください。作成者はデータの損失について責任を負いません。

安全に使用するために

• 1つのボルトにつき、banktivity-cliまたはbanktivity-mcpのプロセスを同時に1つだけ実行してください。書き込みは1つのプロセス内でキューに入れられますが、複数のプロセスにまたがってファイルがロックされることはありません。
• 同じボルトをBanktivity.appで開く前に、banktivity-mcpサーバーを終了してください。アプリとこのツールで、同時にファイルを開いてはいけません。（Banktivityでボルトを開いている間は書き込みが拒否されますが、読み取りは拒否されません。）
• 書き込みを行う前に、毎回バックアップしてください。
• Banktivity 10でボルトを復元、インポート、または移行した後は、口座、取引、明細書、カテゴリのIDを再確認してください。Banktivityによって番号が振り直されることがあります。

このフォークについて

これは、Steve Flinter の banktivity-swift-mcp を david00769 が保守しているフォークです。上流版の機能はすべて含まれています。以下の修正と機能は、上流版に プルリクエストとして提案していますが、上流版では 2026 年 5 月以降、何もマージされていません。

このフォークで追加された機能：

• 同期後も保持される編集。 CLI で行った変更は、次回の Banktivity 同期時に元に戻されなくなりました。
• 明細書： 照合に加え、明細書の行を修復するコマンド。
• 投資： 証券の取引と収益を作成し、ロットごとの実現キャピタルゲインを確認できます。
• 安全性とレポート： 読み取り専用モード、書き込みを行うコマンドの機械可読な一覧、単一の報告通貨による純資産、保有資産の市場価値。
• v0.17.0 の新機能：
  • Core Data が Banktivity のデータベースを書き換えるのを防ぐガード。
  • accounts update。
  • 取引の背後にある銀行からの生のインポートデータを表示する line-items source。
  • 作成時の取引タイプの自動設定。
  • オプションの HTTP サーバーモード。

これらの一部は、他の人のフォークから取り入れたものです。ACKNOWLEDGEMENTS.md に各貢献者を記載し、CHANGELOG.md にリリースごとのすべての変更を記載しています。

どの Banktivity MCP を使えばよいですか？

Banktivity の MCP サーバーを検索すると、関連する 3 つのプロジェクトが見つかります。

プロジェクト	言語	書き込み方法	インストール	状態
mhriemers/banktivity-mcp	TypeScript (npm)	core.sql に 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	保守中。上流版の全機能に加え、フォーク独自の追加機能を搭載

iCloud 経由で同期する保管庫に AI アシスタントから書き込みたい場合は、Core Data を使うプロジェクトを選んでください。3 つとも保管庫を読み取れます。

必要条件

• 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 バンドルです。ダウンロードして Claude Desktop で開くと、拡張機能として banktivity-mcp がインストールされます。Banktivity 10 の保管庫を使う場合は、Vault path を空欄のままにしてください（保管庫の場所を参照）。また、Read-only をオンにすることも検討してください。内部のバイナリはアドホック署名されており、公証はされていません。macOS が実行を拒否する場合は、xattr -dr com.apple.quarantine ~/Library/Application\ Support/Claude/Claude\ Extensions で隔離フラグを削除してから、Claude Desktop を再起動してください。インストールされるのは MCP サーバーのみです。CLI を使う場合は、上記のダウンロードを利用してください。このサーバーは、MCP レジストリ（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 は、リリースビルドと同じようにテストスイートを実行します。リリース構成、ワーカー 1 つ、Xcode のテストフレームワークを使用します。

Homebrew（上流のバージョン）

brew install sflinter/tap/banktivity-swift-mcp

この操作では、このフォークによる変更を含まない上流のバイナリがインストールされます。

リリースの作成方法

CI（.github/workflows/ci.yml）は、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 と同期する保管庫は「書類」ではなく、専用のライブラリに保存されます。

~/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 は、そのフォルダーに保管庫が 1 つだけあれば、それを使用します。**複数ある場合は一覧を表示して停止するため、使用する保管庫を選べます。

**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（絶対パスを指定）と、.bank8 ボルトを指定した環境変数 BANKTIVITY_FILE_PATH の 2 つが必要です（Banktivity 10 のボルトでは省略可能です。ボルトの場所を参照してください）。HTTP 経由で共有サーバーを 1 つ使う方法については、以下を参照してください。シェルコマンドを実行できるエージェントでは、CLI と MCP サーバーのどちらを実行するか、およびボルトの安全な管理もご検討ください。

HTTP 経由で長時間稼働するサーバーを 1 つ実行する

通常、各クライアントは独自の banktivity-mcp を stdio 経由で起動します。たとえば launchd の下で、サーバーを 1 つ起動して稼働し続ける場合は、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" } } }

使用する前に、次の 2 点を確認してください。

• Mac 上のどのプログラムからでも接続できます。 パスワードはないため、このポートはボルトファイルと同じように扱ってください。ほかのサイトのブラウザーページからのリクエストは拒否されます（Origin ヘッダーがチェックされます）。不正な形式のリクエストも拒否されます。
• 稼働中はボルトを開いたままにし、Banktivity で行われた編集は反映されません。 Banktivity でボルトを開く前にサーバーを停止し、その後、再度起動してください。

読み取り専用モード

BANKTIVITY_STORE_READ_ONLY=1（または true、yes）を設定すると、ボルトを読み取り専用で開きます。単に読み込むだけでも、SQLite はライトアヘッドログを整理するため、ディスク上のファイルが変更されます。ボルトの内容を1バイトも変更せずに確認したい場合は、次のようにしてください。

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

このモードでは、書き込みはデータベースに到達した時点で失敗します。SQLite が独自に core.sql-shm を書き込み用に開く場合はあるため、これは追加の保護層です。バックアップは引き続き保管してください。

1つの通貨での純資産と保有資産の価値

純資産（accounts net-worth、get_net_worth、および summary 内の netWorth）は、assets、liabilities、netWorth を返します。これらは通貨換算せず、各口座の現金をそれぞれの通貨で合算したものです。純資産では、さらに次の情報も返されます。

• reportingCurrency と converted：合計額を1つの通貨に換算した値に加え、holdingsValue（投資の市場価値）と netWorthWithHoldings。
• currencyBreakdown：通貨ごとの現金、保有資産、使用した為替レート、換算額。
• warnings：たとえば、ボルトにその通貨の為替レートがないため除外された口座など。

通貨は BANKTIVITY_REPORTING_CURRENCY で指定します（USD などのISOコード）。未設定の場合はEURが使用されます。これまでも合計額に付与されていたラベルです。レートはボルト独自の為替レートテーブルから取得されます。直接のレートがある場合はその最新値、ない場合は逆方向のレートの最新値の逆数、それもない場合はUSD経由の換算が使用されます。

BANKTIVITY_REPORTING_CURRENCY=USD banktivity-cli accounts net-worth

accounts list と accounts balance の投資口座（およびそれらに対応するMCPツール）には、holdingsValue も含まれます。これは保有株数 × 最新の終値 × 証券の価格倍率で計算されます。balance の隣に表示され、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 経由で修復します。同じ BanktivityLib の修復処理は、CLI でも 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、pExchangeRate として exchange_rate、送金先口座の金額として 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 があり、その項目が明細書の残高に加算する金額を示します。投資口座では、amount や accountAmount ではなく statementBalanceAmount を合計してください。証券取引によって現金が移動しても、生の金額には反映されない場合があります。

証券

• 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 が同じボールトを読み書きのために開いたり、同期処理がファイルにアクセスしたりすると、2つのプロセスが同時にデータベースを開くことになります。Banktivity が応答しなくなったりクラッシュしたり、同期が失敗したりする可能性があります。作業が終わったらサーバーを終了できますが、終了を忘れがちです。

CLI は1つのコマンドを実行する間だけボールトを開き、その後終了します。 banktivity-cli はボールトを読み込み、読み取りまたは書き込みを実行して JSON を出力した後に終了するため、Banktivity を開くときにファイルを保持しません。AI エージェントはシェル経由のツール呼び出しが得意なので、Claude Code、Cursor のエージェント、その他のターミナルエージェントは、MCP ツールと同じ作業を CLI 経由で実行できます。Claude Code スキルはまさにそのためのものです。

	banktivity-cli	banktivity-mcp
ボールトを開いたままにする期間	1つのコマンドを実行している間のみ	サーバーの実行中ずっと
最適な用途	Claude Code、ターミナルエージェント、スクリプト、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 を指定すると、スクリプトやエージェントが解析しやすい1行の JSON を出力できます。

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	2つ目の明細項目のカテゴリ。金額には -amount が設定されます
--note	任意のメモ
--transaction-type	check、deposit、transfer、withdrawal のいずれか。省略した場合は自動判定
--line-items	{"account_id" or "account_name", "amount", "memo"?} の JSON 配列。口座、金額、カテゴリの各オプションを置き換えます

アカウントの変更

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は、新しい取引すべてに、データベースがたまたま最初に返した種類（多くの場合「資本の返還」）を割り当てていました。現在は、銀行口座とカードの明細行から種類を判断します。

明細行	種類
異なる銀行口座またはカードアカウントが2つ以上	振替
1つのアカウントで、資金が出ていく	出金
1つのアカウントで、資金が入ってくる	入金

$ 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 は、SHA-256 ダイジェストと照合した、レビュー済みの修復用 JSON プランを実行します
• 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 形式で一覧表示します。

スクリプトで 1 行の JSON が必要な場合は --format compact を使用してください。デフォルトでは、人が確認しやすいように整形済みの JSON が出力されます。

シェル補完

ArgumentParser は、シェル補完スクリプトを自動的に提供します。

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 を呼び出す方法を Claude に教えます。SKILL.md の BANKTIVITY_FILE_PATH を、自分の保管庫を指すように編集する必要があります。

インストール後は、Claude Code の任意のセッションで /banktivity と入力すると有効になります。また、取引、口座、支出、カテゴリについて質問すると、Claude が自動的に有効化します。

安全機能

• 書き込みガード：変更を行う前に、サーバーは Banktivity.app が保管庫を開いているか（lsof 経由で）確認します。開いている場合は、破損を防ぐため書き込みをブロックします。
• スキーマ移行なし：Core Data の自動移行は無効になっています。保管庫から読み込んだデータモデルがデータベースと一致しない場合、ツールは保管庫を開きません。有効のままだと、Core Data はテーブルを削除して再作成することで「移行」します。その結果、あるユーザーは価格レコードを 40,459 件失いました。
• 永続履歴トラッキングなし：Banktivity は独自の同期メカニズムを使用します。Core Data に組み込まれた履歴トラッキングは、認識されないメタデータを追加し、保管庫を破損させる可能性があります。
• バックグラウンドコンテキスト：すべての書き込みで、データの整合性を保つため、performAndWait を使用したバックグラウンドの NSManagedObjectContext インスタンスを使います。
• 保管庫を開いたままにする時間：banktivity-mcp は実行中ずっと保管庫を開いたままにします。banktivity-cli が開くのは、コマンドの実行中だけです。どちらもファイルをロックしません。CLI と MCP サーバーのどちらを実行するか、保管庫を安全に保つ方法をご覧ください。

動作の仕組み

Banktivity の .bank8 バンドルは、Banktivity のコンパイル済みデータモデル（.momd ファイル）と SQLite データベース（StoreContent/core.sql）を格納したフォルダーです。このツールは次の処理を行います。

1. 保管庫からすべての .momd モデルバンドルをファイル名順に読み込み、統合します
2. NSPersistentContainer 経由で SQLite ストアを開きます（履歴トラッキングなし、移行なし）
3. 79 個の MCP ツールを stdio 経由で公開します。または、BANKTIVITY_HTTP_PORT が設定されている場合はループバック HTTP 経由で公開します
4. 実行時に Banktivity 独自のコンパイル済みモデルを読み込むため、KVC（value(forKey:)）を使ってエンティティにアクセスします

よくある質問

Claude（または Cursor、その他の AI エージェント）は、私の Banktivity データを読み取れますか？ はい。MCP クライアントを banktivity-mcp に接続するか（設定）、 シェルを実行できるエージェントに banktivity-cli を実行させてください（CLI）。

iCloud／CloudKit との同期を使っていても安全ですか？ 書き込みは Banktivity と同じように Core Data 経由で行われるため、同期に反映されます （CloudKit 同期の安全性：Core Data を使う理由（SQLite に直接アクセスしない理由））。 Banktivity で同じ保管庫を開いている間は実行せず、事前にバックアップしてください。

「macOS が Banktivity のライブラリへのアクセスをブロックしました」というメッセージが表示され、拡張機能が失敗します。 まず macOS でアクセスを許可する必要があります。banktivity-mcp プログラム自体をフルディスクアクセスに追加してください （macOS でアクセスを許可する）。

MCP サーバーの実行中に Banktivity を開くと問題が起きますか？ 問題が起きる可能性があります。サーバーは保管庫を開いたままにします。Banktivity を開く前にサーバーを終了するか、 CLI を使用してください（CLI と MCP サーバーのどちらを実行するか、保管庫を安全に保つ方法）。

Banktivity 10 と .bank8 ファイルで動作しますか？ はい。.bank8 バンドル内にある Banktivity 独自のデータモデルを読み込みます （動作の仕組み）。

AI に読み取り専用アクセスを許可できますか？ BANKTIVITY_STORE_READ_ONLY=1 を設定し（読み取り専用モード）、banktivity-cli capabilities を実行して、書き込みを行うコマンドを確認してください。これは安全対策であり、サンドボックスではありません。シェルコマンドを実行できるエージェントはこの変数を解除できるため、書き込みをさせてはいけない場合は、保管庫のコピーを渡してください。

謝辞

このフォークには、Steve Flinter によるオリジナルをベースに、Peter Baker、Roberto Michelena、producethis、 muxadil、Richard Jeans、Howy Perrin、Martijn Riemers による成果が含まれています。ACKNOWLEDGEMENTS.md に、各貢献の内容と由来、取り入れた方法を記載しています。

ライセンス

ライセンスは2種類あります。どの部分にどちらが適用されるかは、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]）から商用ライセンスを取得する必要があります。