## Sovereign Data: The Philosophy

For decades, our personal financial history has been locked inside proprietary desktop ecosystems or tied to cloud-based aggregators. We believe in a third path: local-first data interrogated by local-first AI.

Rather than capping what an intelligent agent can do by wrapping the database in a rigid REST-like API, we have pivoted this project toward Skills-first design and complete data sovereignty. We expose the raw database schema and provide an excellent technical paper trail, empowering modern, hyper-intelligent agents to write and execute highly relational, unexpected SQL queries on the fly.

Read the full case study on this paradigm shift in Data Sovereignty, AI Agents, and Why Technical Docs Are the New APIs on David Weekly's personal blog.

## Two Integration Paths

This repository ships two companion integration methods sharing the identical audited database schema:

### 1. Agent Skill Recommended

Teaches Claude to read your Quicken SQLite database directly using your system's preinstalled `sqlite3` tool.

No background servers, no module compile errors. Simply loads the raw database schema and a comprehensive set of query recipes into Claude's prompt context, letting the model construct precise relational queries dynamically.

View SKILL.md

### 2. MCP Server

Wraps common relational queries into 8 prepackaged tools for environments that do not support raw skill injection.

Ideal for non-Claude clients like Cursor, Cline, or custom MCP gateways that require typed tools instead of SQL generation.

Explore MCP Tools

## Sovereign Exporter New

Want to free your multi-decade financial records permanently? This project includes a zero-dependency, pure Python command-line tool that conects to your active Quicken database and parses it into a fully portable, normalised folder package.

Execute the exporter in one command:

    python3 scripts/export_sovereign_csv.py

It creates a `quicken_sovereign_export/` folder containing:

- Standardised CSVs: `accounts.csv`, `categories.csv`, `payees.csv`, `transactions.csv`, `transaction_splits.csv`, `tags.csv`, and `holdings.csv` (reconstructing individual tax lots and cost basis).
- Relational Map (`schema.json`): A comprehensive data dictionary defining every column, type, description, and foreign key reference.
- Migration Guide (`README.md`): A detailed guide showing you how to immediately query this data using DuckDB, Pandas, or PostgreSQL.

This package allows any local LLM, custom database agent, or self-hosted tool to immediately digest your full financial history without intermediate wrappers.

## Packaged MCP Tools

If utilizing the MCP wrapper pathway, the server exposes the following 8 tools directly to your workspace client:

Tool | Description
--- | ---
`list_accounts` | Exposes bank accounts, credits, assets, liabilities, and retirement funds.
`list_categories` | Lists hierarchical category tags, distinguishing income and expense items.
`query_transactions` | Retrieves transactions with advanced filters (dates, payees, amount, categories).
`spending_by_category` | Aggregates category spending summaries for a designated date range.
`spending_over_time` | Monthly cash-flow trends, optionally broken down by category splits.
`search_payees` | Lists and searches registered payee merchants.
`list_portfolio` | Lists active holdings with cost basis, shares, and current price quotes.
`raw_query` | Executes arbitrary read-only `SELECT` statements against the SQLite database.

## Installation & Setup

### Claude Code (As a Plugin)

Installs both the recommended `/quicken` skill and the MCP server tools in one step:

    claude plugin install quicken-mac-mcp

### Claude Desktop (Manual Config)

Open your Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json`) and add:

    {
      "mcpServers": {
        "quicken": {
          "command": "npx",
          "args": ["-y", "quicken-mac-mcp"]
        }
      }
    }

Note: Quicken For Mac must be open and unlocked while your agent runs; Quicken encrypts the SQLite database on disk when the application is closed.

## Database Schema

The Quicken database is a clean Core Data SQLite file. The following table describes the main physical schemas audited and mapped by our integration guide:

Table Name | Description / Role
--- | ---
`ZACCOUNT` | Accounts, balances, types, and closing statuses.
`ZTRANSACTION` | Master transaction records (post dates, numbers, payees).
`ZCASHFLOWTRANSACTIONENTRY` | Relational split entries (amounts, categories, tags).
`ZTAG` (Z_ENT=79) | Hierarchical financial categories (income vs expense splits).
`ZUSERPAYEE` | Merchant lists and quick-fill defaults.
`ZLOT` / `ZPOSITION` | Tax lots, investment purchases, cost basis.
`ZSECURITY` | Public securities (stock symbols, current prices).

Time Representation: Core Data SQLite tables represent time as the number of seconds elapsed since 2001-01-01 00:00:00 UTC (Core Data Epoch). Both the Skill instructions and the MCP server handle this conversion automatically.

## Disclaimer

This project is an independent, community-developed open-source tool. It is not an official Intuit product and is not endorsed by, directly affiliated with, maintained by, or sponsored by Intuit Inc. or any of its subsidiaries. "Quicken" is a registered trademark of Intuit Inc. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

This software is provided "as is," without warranty of any kind. The authors and contributors are not responsible for any damage, data loss, or other issues arising from its use. Always back up your financial database before utilizing local analytics integrations.