Banktivity

banktivity-swift-mcp: Banktivity MCP server and CLI for AI assistants

A Swift library, Model Context Protocol (MCP) server and command-line tool for Banktivity personal finance files. It lets Claude Desktop, Claude Code, Cursor and other MCP clients or AI agents read and write a Banktivity 10 .bank8 vault: accounts, transactions, splits, categories, payees, tags, templates, import rules, scheduled transactions, statements and securities. It can also export a vault as RDF.

• banktivity-cli is the command-line tool, for scripts, for AI agents that run shell commands, and for looking things up yourself.
• banktivity-mcp is an MCP server with 80 tools, so an AI assistant such as Claude can work with your vault.
• BanktivityLib is the library both are built on. It has no server dependencies.

Every change goes through Core Data, the way Banktivity itself writes, so edits are seen by Banktivity's iCloud/CloudKit sync. See CloudKit sync safety.

CloudKit sync safety: why Core Data, not direct SQLite

A .bank8 vault is a Core Data store, and Banktivity syncs it through CloudKit.

• Writing SQLite directly is invisible to sync. A tool that writes core.sql with SQL bypasses Core Data's change tracking. CloudKit sync never sees those edits, so they can fail to sync, be reverted, or corrupt the vault. Martijn Riemers's TypeScript banktivity-mcp, which inspired the Swift rewrite, was built that way.
• This tool writes through Core Data. Steve Flinter's Swift rewrite opens the vault with NSPersistentContainer, using Banktivity's own compiled data model, and makes every change through it, as Banktivity does.
• Writes are refused while Banktivity has the vault open (an lsof check, from the Swift rewrite).
• This fork adds more guards. CLI edits are no longer reverted by the next sync, Core Data is never allowed to migrate (rewrite) Banktivity's database, and the write guard now refuses when it cannot tell and is enforced where every write is saved. See Safety Features.

Warning: this tool changes your Banktivity data. Write commands make real

changes to your vault, and AI assistants make mistakes. Back up the vault before

any write session, and work on a copy until you trust your setup. The authors

are not responsible for data loss.

Using it safely

• Run one banktivity-cli or banktivity-mcp process per vault at a time. Writes are queued inside one process, but nothing locks the file across processes.
• Quit any banktivity-mcp server before you open the same vault in Banktivity.app. The app and this tool must not have the file open together. (Writes are refused while Banktivity has the vault open, but reads are not.)
• Back up before every write session.
• After restoring, importing or migrating a vault in Banktivity 10, look up account, transaction, statement and category IDs again. Banktivity can renumber them.

About this fork

This is david00769's maintained fork of Steve Flinter's banktivity-swift-mcp. It has everything upstream has. Upstream merged nine of this fork's pull requests on 2026-11-03, so much of the fork's earlier work is in upstream too. Some of what is listed below is still offered upstream as pull requests; the rest is only here.

What the fork adds:

• Edits that survive sync. Changes made with the CLI are no longer reverted the next time Banktivity syncs.
• Statements: reconciliation that selects the same rows the Banktivity app does, plus repair commands for statement rows.
• Investments: create security trades and income, and see realised capital gains per lot.
• Safety and reporting: a machine-readable list of which commands write, net worth in one reporting currency, and an investment account's holdings value on its balance.
• New in v0.17.0:
• a guard that stops Core Data from rewriting Banktivity's database;
• accounts update;
• line-items source, showing the raw bank import behind a transaction;
• automatic transaction types on create;
• an optional HTTP server mode.

Some of this came from other people's forks. ACKNOWLEDGEMENTS.md credits each contribution, and CHANGELOG.md lists every change by release.

Which Banktivity MCP should I use?

Three related projects come up when you search for a Banktivity MCP server:

If you want an AI assistant to write to a vault that syncs through iCloud, use one of the Core Data projects. All three can read a vault.

Requirements

• macOS 14 or later
• A Banktivity .bank8 vault

Installation

Download a release (recommended)

Each release has one universal download (Apple Silicon and Intel) and a checksum file. CI builds and tests the release from the tagged commit. For v0.17.4:

base=https://github.com/david00769/banktivity-swift-mcp/releases/download/v0.17.4

curl -LO "$base/banktivity-swift-mcp-v0.17.4-macos-universal.tar.gz" curl -LO "$base/banktivity-swift-mcp-v0.17.4-macos-universal.tar.gz.sha256" shasum -a 256 -c banktivity-swift-mcp-v0.17.4-macos-universal.tar.gz.sha256 # prints "OK"

tar xzf banktivity-swift-mcp-v0.17.4-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.4

The binaries are signed ad hoc, not notarized. The xattr line removes the quarantine flag macOS puts on downloaded files, which would otherwise stop them from running.

Claude Desktop extension (.mcpb)

Each release also has banktivity-swift-mcp-vX.Y.Z-macos-universal.mcpb, an MCP Bundle. Download it and open it with Claude Desktop to install banktivity-mcp as an extension. Leave Vault path blank to use your Banktivity 10 vault (see Where is my vault?), and consider turning Read-only on. The binary inside is ad-hoc signed, not notarized; if macOS refuses to run it, clear the quarantine flag with xattr -dr com.apple.quarantine ~/Library/Application\ Support/Claude/Claude\ Extensions and restart Claude Desktop. It installs only the MCP server; for the CLI, use the download above. The server is also listed in the MCP Registry as io.github.david00769/banktivity-swift-mcp.

Build from source

Xcode 16 or later is recommended. Without Xcode the Makefile falls back to the Command Line Tools for building and installing (not tested here); running the tests needs Xcode.

git clone https://github.com/david00769/banktivity-swift-mcp.git

cd banktivity-swift-mcp make install # universal build, installed to ~/.local/bin

Always install with make install (or make install-fast for a quicker single-architecture build). Never copy a new binary over ~/.local/bin with cp. cp rewrites the file in place, and a banktivity-mcp still running from it is killed by macOS the next time it starts ("Code Signature Invalid"). The Makefile copies to a temporary name, signs it, then renames it into place.

Other Makefile targets:

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 runs the suite the way a release build behaves: release configuration, one worker, Xcode's test frameworks.

Homebrew (upstream's version)

brew install sflinter/tap/banktivity-swift-mcp

This installs upstream's binaries, without this fork's changes.

How releases are made

CI (.github/workflows/ci.yml) runs on every push and pull request to main. It runs make test, then make package, so a change that breaks the release build fails before anyone tags it. To release, bump Sources/BanktivityLib/Version.swift and add a matching section to CHANGELOG.md, then push a tag:

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

.github/workflows/release.yml then checks that the tag matches Version.swift, runs the tests, builds the tarball and publishes the release. The CHANGELOG section becomes the release notes.

Configuration

Where is my vault?

Banktivity 10 keeps a vault that syncs through Banktivity Cloud in its own library, not in Documents:

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

The folder differs from Mac to Mac. If `BANKTIVITY_FILE_PATH` is unset or empty, `banktivity-mcp` and `banktivity-cli` use the vault in that folder, provided there is exactly one. With several they list them and stop, so you can pick one.

macOS asks permission first. That folder belongs to Banktivity, and macOS protects one app's data from other apps, so the first run is blocked until you grant access. See Granting access on macOS.

A vault saved anywhere else (the examples below use ~/Documents/Banktivity/My Accounts.bank8) needs its path set. The path must end in .bank8; if you give a folder, the error lists the vaults inside it.

Granting access on macOS

macOS blocks other programs from reading Banktivity 10's library until you allow it. Until then the server logs:

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

and Claude Desktop shows the extension as failed. You may also get a macOS notification about a program accessing "data from other apps". To fix it:

1. Quit Banktivity.
2. Open **System Settings > Privacy & Security > Full Disk