Banktivity Swift Mcp

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 across payees, memos, etc.
• get_transaction — Get a single transaction by ID
• create_transaction — Create a new transaction
• update_transaction — Update an existing transaction
• delete_transaction — Delete a transaction

Line Items

• get_line_item — Get a specific line item
• add_line_item — Add a line item to a transaction (for splits)
• update_line_item — Update a line item
• delete_line_item — Delete a line item

Categories

• list_categories — List all income/expense categories
• get_category — Get a specific category
• get_category_tree — Get the full category hierarchy
• create_category — Create a new category

Categorization

• get_uncategorized_transactions — Find transactions without categories
• suggest_category_for_merchant — Suggest a category based on merchant history
• recategorize_transaction — Change a transaction's category
• bulk_recategorize_by_payee — Recategorize all transactions for a payee
• review_categorizations — Review recent categorization changes
• get_payee_category_summary — Summary of categories used per payee

Tags

• get_tags — List all tags
• create_tag — Create a new tag
• tag_transaction — Tag a transaction
• get_transactions_by_tag — Find transactions with a specific tag
• bulk_tag_transactions — Tag multiple transactions at once

Templates

• list_transaction_templates — List saved transaction templates
• get_transaction_template — Get a specific template
• create_transaction_template — Create a new template
• update_transaction_template — Update a template
• delete_transaction_template — Delete a template

Import Rules

• list_import_rules — List all import rules
• get_import_rule — Get a specific import rule
• match_import_rules — Find rules matching a payee string
• create_import_rule — Create a new import rule
• update_import_rule — Update an import rule
• delete_import_rule — Delete an import rule

Scheduled Transactions

• list_scheduled_transactions — List all scheduled transactions
• get_scheduled_transaction — Get a specific scheduled transaction
• create_scheduled_transaction — Create a new scheduled transaction
• update_scheduled_transaction — Update a scheduled transaction
• delete_scheduled_transaction — Delete a scheduled transaction

Statements (Reconciliation)

• list_statements — List statements for an account
• get_statement — Get a statement with reconciliation progress
• create_statement — Create a new statement with balance validation
• delete_statement — Delete a statement and unreconcile its line items
• reconcile_line_items — Assign line items to a statement
• unreconcile_line_items — Remove line items from a statement
• get_unreconciled_line_items — List unreconciled line items for an account

Securities

• list_securities — List all securities with name, symbol, and currency
• create_security — Create a new security with symbol, name, and currency
• get_security_prices — Get price history for a security (by symbol or ID, optional date range/limit)
• get_security_holdings — Get current holdings (positions) with shares, cost basis, and market value
• get_security_trades — Get trade history (buys, sells, transfers) with shares, prices, and commissions
• get_security_income — Get investment income (dividends, interest, capital gains distributions)
• create_share_adjustment — Create a share adjustment (e.g. charges, stock splits, position corrections)
• import_security_prices — Import prices from a CSV file (Yahoo Finance, OHLCV, or Date/Close)
• delete_security_prices — Delete price history for a security (optional date range)

Export

• export_turtle — Export the entire vault as RDF/Turtle (.ttl), optionally to a file

Diagnostic

• dump_schema — Inspect the Core Data model schema (entity names, attributes, relationships)

CLI

A standalone CLI (banktivity-cli) provides the same functionality without an MCP server. Set BANKTIVITY_FILE_PATH or pass --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 Subcommands

• 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

Most commands that accept --account-id also accept --account-name as an alternative. The transactions create command supports --line-items with a JSON array for multi-line-item (split) transactions.

Use --format compact for machine-readable single-line JSON output (default is pretty-printed).

Shell Completions

ArgumentParser provides shell completion scripts automatically:

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

For example, to install Zsh completions:

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

Claude Code Skill

A /banktivity skill is available for Claude Code. It lets Claude use the CLI directly to answer natural-language questions about your finances — "What did I spend on groceries last month?", "Show me uncategorized transactions in Checking", etc.

To install, copy the skill directory into your global Claude Code config:

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

The skills/banktivity/ directory contains a SKILL.md file that teaches Claude how to invoke banktivity-cli with the correct environment variable and arguments. You'll need to edit the BANKTIVITY_FILE_PATH in SKILL.md to point to your own vault.

Once installed, type /banktivity in any Claude Code session to activate it, or Claude will activate it automatically when you ask about transactions, accounts, spending, or categories.

Safety Features

• Write guard: Before any mutation, the server checks if Banktivity.app has the vault open (via lsof). If it does, writes are blocked to prevent corruption.
• No persistent history tracking: Banktivity uses its own sync mechanism. Core Data's built-in history tracking would add unrecognized metadata that corrupts the vault.
• Background contexts: All writes use background NSManagedObjectContext instances with performAndWait for data integrity.

How It Works

Banktivity's .bank8 bundle is a directory containing compiled Core Data models (.momd files) and a SQLite database (StoreContent/core.sql). This server:

1. Loads and merges all .momd model bundles from the vault
2. Opens the SQLite store via NSPersistentContainer (no history tracking)
3. Exposes 64 MCP tools over stdio transport
4. Uses KVC (value(forKey:)) to access entities since we load Banktivity's own compiled models at runtime

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sflinter
• Source: sflinter/banktivity-swift-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.