banktivity-swift-mcp

A Swift library, MCP server, and CLI for Banktivity personal finance files. Provides full read/write access to .bank8 vaults — accounts, transactions, categories, tags, templates, import rules, scheduled transactions, statements, securities, and RDF export.

• BanktivityLib — pure domain library with Core Data repositories and RDF export, no server dependencies
• banktivity-mcp — MCP server exposing 64 tools over stdio, for AI assistants like Claude
• banktivity-cli — standalone CLI for scripting and automation

Inspired by banktivity-mcp (TypeScript/Node.js), this is a ground-up rewrite in Swift. The original uses better-sqlite3 to read and write Core Data's SQLite store directly, bypassing Core Data's internal change tracking. This works for reads, but direct SQL writes are invisible to CloudKit sync — Banktivity doesn't know the data changed, and the vault can become corrupted or fail to sync. This Swift version uses NSPersistentContainer so all mutations go through Core Data's API, ensuring proper change tracking and CloudKit compatibility.

WARNING: This server can modify your Banktivity data. Write tools (create, update, delete) make real changes to your .bank8 vault. While the server uses Core Data for proper change tracking and includes a write guard that blocks mutations when Banktivity is open, AI assistants can and will make mistakes. Back up your vault regularly and consider working on a copy until you're confident in your workflow. The authors are not responsible for any data loss or corruption.

Requirements

• macOS 14+
• A Banktivity .bank8 vault file

Installation

Homebrew (recommended)

brew install sflinter/tap/banktivity-swift-mcp

This installs both banktivity-mcp and banktivity-cli as universal binaries (Apple Silicon + Intel).

Download binary

Download the universal binary from GitHub Releases, extract, and move to your PATH:

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

Build from source

Requires Xcode 16+ (needed for Swift Testing and universal binary builds):

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

Other Makefile targets:

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

Configuration

Claude Code

Add to your MCP settings (~/.claude/settings.json or project .mcp.json):

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

Claude Desktop

Add to ~/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"
      }
    }
  }
}

Available Tools

Accounts

• list_accounts — List all accounts with balances
• get_account_balance — Get balance for a specific account
• get_net_worth — Calculate total net worth
• get_spending_by_category — Spending breakdown by category for a date range
• get_income_by_category — Income breakdown by category for a date range
• get_summary — Overall financial summary

Transactions

• get_transactions — List transactions with filtering and pagination
• search_transactions — Full-text search

... View full README on GitHub