quicken-mac-mcp

quicken-mac-mcp

一个 Claude 技能 + MCP 服务，让 Claude 能够以只读方式访问你的 Quicken For Mac 财务数据。你可以向 Claude 询问账户、交易、按类别划分的支出、月度趋势、投资持仓等信息。

数据库始终以只读方式打开——绝不会修改你的 Quicken 数据。

应该选技能还是 MCP？

本仓库提供两个使用相同架构知识（docs/schema.md）的组件：

• 技能（plugin/skills/quicken/SKILL.md）——教 Claude 使用 Python 3 标准库中的 SQLite 支持，直接探查并读取 Quicken SQLite 数据库。其专门的 references/ 涵盖余额、现金流、投资、预算、标签和 QuickFill 规则。可在 Claude Code 以及任何支持加载技能的 Claude 平台上使用。**无需安装原生模块，也无需运行 MCP 服务进程。**这是推荐的方式。
• MCP 服务——将相同的 SQL 查询方案封装为八个预打包工具（list_accounts、query_transactions、spending_by_category，……）。如果你使用的是无法加载技能的非 Claude MCP 客户端（Cursor、Cline、mcp-remote 桥接程序），或者更希望调用类型化工具而不是让 Claude 编写 SQL，可以使用此方式。

安装 Claude Code 插件（claude plugin install quicken-mac-mcp）后会同时包含这两者，以技能为主，并提供 MCP 工具作为快捷方式。

要求

使用技能或 MCP 时，必须保持 Quicken For Mac 开启。关闭应用后，Quicken 会加密数据库文件——只有在 Quicken 运行时才能读取数据。

工作原理

Quicken For Mac 将数据存储在 Documents 文件夹内 .quicken 捆绑包中的 Core Data SQLite 数据库里（例如 ~/Documents/MyFinances.quicken/data）。技能会教 Claude 如何直接查询该数据库；MCP 服务则是一个精简封装，将八个预打包查询作为工具提供。

安装——推荐方式（Claude Code，插件）

claude plugin install quicken-mac-mcp

这会同时安装 /quicken 技能（推荐方式）和 MCP 服务。Claude 会优先使用技能，并在合适时使用 MCP 工具。

安装——仅 MCP 的方式

如果你使用的是无法加载技能的非 Claude Code 客户端，或者只需要类型化工具封装，请使用以下方式。

Claude Code（仅 MCP）

claude mcp add quicken -- npx -y quicken-mac-mcp

Claude Desktop（拖放 MCPB）

从最新的 GitHub 版本下载适用于你 Mac 的捆绑包，然后将其拖入 Claude Desktop：

• Apple Silicon：quicken-mac-mcp-arm64.mcpb
• Intel：quicken-mac-mcp-x64.mcpb

系统会提示你输入数据库路径（或自动检测路径）。

Claude Desktop（手动 JSON 配置）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

重启 Claude Desktop 后，你会看到一个锤子图标，表示有 8 个工具可用。

自定义数据库路径

如果你有多个 Quicken 文件，或者 .quicken 捆绑包不在 ~/Documents 中，请设置 QUICKEN_DB_PATH 环境变量：

{
  "mcpServers": {
    "quicken": {
      "command": "npx",
      "args": ["-y", "quicken-mac-mcp"],
      "env": {
        "QUICKEN_DB_PATH": "/path/to/YourFile.quicken/data"
      }
    }
  }
}

默认情况下，只有当 ~/Documents 中恰好有一个 .quicken 捆绑包时，服务才会自动检测 Quicken 数据库。如果存在多个捆绑包，服务不会猜测；请明确设置 QUICKEN_DB_PATH。

MCP 工具

以下是 MCP 服务提供的八个预打包工具。通过直接对数据库编写 SQL，技能可以完成相同的工作（甚至更多）——请参阅 plugin/skills/quicken/SKILL.md。

工具	描述
list_accounts	列出所有账户及其名称、类型和启用／关闭状态。可选类型筛选。
list_categories	列出所有分类标签及其父级层级。可按支出／收入筛选。
query_transactions	按日期范围、账户类型／名称、金额范围、收款方搜索和分类筛选交易。每个拆分条目返回一行，附带 note（交易级）和 split_note（拆分级）备注。
spending_by_category	按分类汇总消费者支出的负数拆分，排除转账和报表排除行，并保留 (Uncategorized)。
spending_over_time	按月汇总消费者支出的负数金额，采用相同的排除规则；也可按分类细分。
search_payees	按名称搜索收款方，并显示交易计数。
list_portfolio	列出投资持仓，包括份额、成本基础和 Quicken 中存储的报价。
raw_query	运行任意 SELECT 查询（最多 500 行）。

自描述命令行界面（qmac）

本项目包含功能齐全、自带说明的命令行界面 qmac，可让你直接在终端查询 Quicken SQLite 数据库，而无需通过 MCP 客户端。

功能：

• 集中式架构验证：将参数动态转换为正确类型（数字、布尔值、数组）并进行验证。
• 子命令帮助（--help / -h）：轻松查看任何子命令的参数说明和类型（例如 qmac spending-by-category --help）。
• 语法错误自动显示帮助：语法错误或缺少必填字段时，会输出准确的错误信息以及该子命令的帮助页面。
• 集成手册（qmac man）：直接在 shell 中呈现完整、样式精美的 UNIX man 手册指南。
• 优质 ASCII 表格布局：列宽会自动调整，数字右对齐，表头清晰易读。使用 --json 获取原始数据以便编写脚本。

示例命令：

# General help
qmac --help

# Render stylized manual page
qmac man

# List checking accounts
qmac list-accounts --account-type checking

# Find Costco transactions over $100 in 2024
qmac query-transactions --start-date 2024-01-01 --end-date 2024-12-31 --payee-search costco --max-amount -100

# Get subcategory spending breakdown for Q1 2025
qmac spending-by-category --start-date 2025-01-01 --end-date 2025-03-31 --group-by category

# Display investment portfolio holding valuations
qmac list-portfolio

提示词示例

• “列出我的账户”
• “上个月我在食品杂货上花了多少钱？”
• “显示我 2024 年按分类统计的支出”
• “过去一年我的月支出有何变化？”
• “查找 Costco 的所有金额超过 100 美元的交易”
• “按交易笔数列出前 10 个收款方”
• “比较我 2024 年和 2025 年的食品支出”

主权财务导出工具（CSV 和关系型 schema.json）

想将完整的个人财务历史从 Quicken 迁移到自己的主权化、可自托管或自定义 Agent 分析平台吗？

本项目包含一个高速、零依赖的纯 Python 工具 scripts/export_sovereign_csv.py，它会连接到已解锁的 Quicken 数据库，并将数据提取为规范化、可移植的整洁数据包。

如何使用导出器：

1. 打开 Quicken For Mac 应用并登录，以解密数据库。
2. 在终端中执行导出脚本：

   python3 scripts/export_sovereign_csv.py
   

3. 系统将生成一个新目录 quicken_sovereign_export/，其中包含：
   • accounts.csv：经过规范化处理的账户列表（支票账户、信用账户、经纪账户、退休账户等）。
   • categories.csv：收入和支出类别路径结构。
   • payees.csv：已登记的商户名称列表。
   • transactions.csv：顶层分类账，包含入账日期、备注和交易级详细信息。
   • transaction_splits.csv：显示金额和类别 ID 的明细拆分项。
   • holdings.csv：根据个人税务批次重建的活跃投资持仓，包含成本基础和未实现收益。
   • tags.csv：直接映射到拆分项的自定义用户标签。
   • schema.json：完整的关系型列和外键引用字典。
   • README.md：详细的迁移指南，演示如何立即在 DuckDB、Pandas、PostgreSQL 或其他数据库中加载和查询你的财务历史记录。

这样，其他 Agentic 平台（例如自定义 GPT、可自托管的大模型或主权数据库 Agent）就能立即解析、导入并分析你的全部财务历史记录。

---

数据库架构

Quicken For Mac 使用 Core Data，并包含以下关键表：

表	用途
ZACCOUNT	银行账户、信用卡、投资账户
ZTRANSACTION	单笔交易（包含交易级备注 ZNOTE）
ZCASHFLOWTRANSACTIONENTRY	拆分明细项——类别和每个拆分项的 ZNOTE 备注都存储在此处
ZTAG	带有父级层次结构的类别标签（运行时查询 Z_ENT）
ZUSERPAYEE	收款方名称

日期使用 Core Data 纪元（自 2001-01-01 起的秒数）。MCP 服务会自动处理所有日期转换——你传入 ISO 8601 日期，它就返回 ISO 8601 日期。技能配方会直接展示转换方式（+ 978307200），以便 Claude 直接编写 SQL。

账户类型以大写字符串存储：CHECKING、CREDITCARD、SAVINGS、MORTGAGE、RETIREMENTIRA、ASSET、LIABILITY、LOAN 等。工具接受任意大小写形式。

完整的架构参考（84 个实体、所有表、索引、外键以及 Core Data 写入语义，包括 Z_OPT 乐观锁定），请参阅 docs/schema.md。

开发

git clone https://github.com/dweekly/quicken-mac-mcp.git
cd quicken-mac-mcp
npm install
npm test          # run tests
npm run lint      # eslint
npm run format    # prettier
npm run dev       # run server locally

如果 ~/Documents 中有多个 .quicken 包，请在运行 npm test 前设置 QUICKEN_DB_PATH；否则，实时架构测试套件会跳过。

已知问题和计划中的工作见 ROADMAP.md——包括未修复的错误、开发者体验方面的不足，以及延期的依赖项升级（截至 2026-08-14 的最新信息）。

Docker

docker build -t quicken-mac-mcp .
docker run --rm -v ~/Documents/YourFile.quicken:/data:ro quicken-mac-mcp

贡献者

• Manish Mukherjee — 修复了 CategoryTag 的动态 Z_ENT 查询（#4），为导入的交易添加了 account_names 筛选器和日期回退机制（#5）
• Als-Pal — Quicken ↔ Amazon 订单匹配器 gist 揭示了备注存储在两个层级（ZTRANSACTION.ZNOTE 和 ZCASHFLOWTRANSACTIONENTRY.ZNOTE），并记录了 Z_OPT 写回语义；这些内容现已收录在 docs/schema.md 中。

免责声明

本项目是一款由社区独立开发的开源工具。它不是 Intuit 的官方产品，也未获得 Intuit Inc. 或其任何子公司的认可、直接关联、维护或赞助。“Quicken”是 Intuit Inc. 的注册商标。所有产品名称和公司名称均为其各自持有者的商标或注册商标。使用这些名称并不代表与其存在任何关联，也不代表获得其认可。

本软件按“原样”提供，不附带任何形式的保证。作者和贡献者不对因使用本软件而造成的任何损害、数据丢失或其他问题负责。使用第三方工具前，请务必备份您的财务数据。

许可证

MIT