quicken-mac-mcp

quicken-mac-mcp

Claude に Quicken For Mac の財務データへの読み取り専用アクセスを提供する Claude スキル + MCP サーバー です。口座、取引、カテゴリ別の支出、月ごとの傾向、投資保有資産などについて Claude に質問できます。

データベースは常に読み取り専用で開かれるため、Quicken のデータが変更されることはありません。

スキルと MCP — どちらを選べばよいですか？

このリポジトリには、同じスキーマ知識（docs/schema.md）を共有する 2 つの成果物が含まれています。

• スキル（plugin/skills/quicken/SKILL.md） — Python 3 の標準ライブラリにある SQLite サポートを使って、Quicken の SQLite データベースを直接調査し、読み取る方法を Claude に教えます。専用の references/ では、残高、キャッシュフロー、投資、予算、タグ、QuickFill ルールを扱います。Claude Code や、スキルを読み込むその他の Claude 環境で利用できます。ネイティブモジュールのインストールも MCP サーバープロセスも不要です。 推奨される方法です。
• MCP サーバー — 同じ SQL の手順を、あらかじめ用意された 8 つのツール（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 サーバーは、あらかじめ用意された 8 つのクエリをツールとして公開する軽量なラッパーです。

インストール — 推奨（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 バンドルが 1 つだけ存在する場合に限り、サーバーが Quicken データベースを自動検出します。複数のバンドルが存在する場合、推測して選択することはありません。QUICKEN_DB_PATH を明示的に設定してください。

MCP ツール

以下は、MCP サーバーが公開する8つの組み込みツールです。このスキルでは、データベースに SQL を直接記述することで同じ範囲（さらに多くの内容）をカバーしています。plugin/skills/quicken/SKILL.md を参照してください。

ツール	説明
list_accounts	名前、種類、有効／閉鎖状態を含むすべての口座を一覧表示します。種類による絞り込みは任意です。
list_categories	親階層を含むすべてのカテゴリタグを一覧表示します。支出／収入による絞り込みが可能です。
query_transactions	日付範囲、口座の種類／名前、金額範囲、受取人の検索、カテゴリで取引を絞り込んで検索します。分割項目ごとに1行を返し、note（取引単位）とsplit_note（分割項目単位）のメモを含みます。
spending_by_category	カテゴリ別に、マイナスの消費支出の分割項目を集計します。振替とレポート対象外の行は除外し、(Uncategorized)は保持します。
spending_over_time	同じ除外条件を適用した、月ごとのマイナスの消費支出合計を返します。カテゴリ別の内訳も指定できます。
search_payees	取引件数とともに、名前で受取人を検索します。
list_portfolio	株式数、取得原価、Quicken に保存された価格見積もりを含む投資保有資産を一覧表示します。
raw_query	任意の SELECT クエリを実行します（最大500行）。

自己文書化コマンドラインインターフェース（qmac）

このプロジェクトには、MCP クライアントを介さずに、ターミナルから Quicken の SQLite データベースを直接照会できる、機能が充実した自己文書化コマンドラインインターフェース qmac が含まれています。

機能：

• 一元化されたスキーマ検証：引数は数値、ブール値、配列などの正しい型に動的に変換され、検証されます。
• サブコマンドのヘルプ（--help / -h）：任意のサブコマンドのパラメーターの説明と型を簡単に確認できます（例：qmac spending-by-category --help）。
• 構文エラー時の自動ヘルプ表示：構文が正しくない場合や必須フィールドが不足している場合、正確なエラーメッセージとサブコマンドのヘルプページが表示されます。
• 統合マニュアル（qmac man）：スタイル付きの UNIX マニュアルページをシェル上にそのまま表示します。
• 高品質な 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年のカテゴリ別支出を表示して」
• 「過去1年間で月ごとの支出はどのように変化した？」
• 「Costco での100ドルを超える取引をすべて検索して」
• 「取引件数が多い上位10件の受取人は？」
• 「2024年と2025年の食費を比較して」

主権型金融エクスポーター（CSV およびリレーショナル schema.json）

Quicken から個人の金融履歴全体を取り出して、自分で管理するセルフホスト型またはカスタムのエージェント型分析プラットフォームへ移行したいですか？

このプロジェクトには、高速で依存関係のない純粋な 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などのデータベース向けの詳細な移行ガイド。

これにより、カスタム GPT、セルフホスト型 LLM、独自のデータベースエージェントなどのエージェント型プラットフォームが、財務履歴全体をすぐに解析、取り込み、分析できるようになります。

---

データベーススキーマ

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 のエンティティ、すべてのテーブル、インデックス、外部キー、および Z_OPT の楽観的ロックを含む Core Data の書き込みセマンティクス）については、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 によって、メモが 2 つのレベル（ZTRANSACTION.ZNOTE と ZCASHFLOWTRANSACTIONENTRY.ZNOTE）に格納されていることが明らかになり、現在 docs/schema.md に記載されている Z_OPT の書き戻しセマンティクスが文書化されました。

免責事項

このプロジェクトは、コミュニティが独自に開発したオープンソースツールです。Intuit の公式製品ではなく、Intuit Inc. またはその子会社による推奨、直接的な提携、保守、スポンサー提供を受けていません。「Quicken」は Intuit Inc. の登録商標です。すべての製品名および会社名は、それぞれの所有者の商標または登録商標です。これらの名称を使用していても、各社との提携や推奨を意味するものではありません。

このソフトウェアは、いかなる種類の保証もなく「現状のまま」提供されます。作者および貢献者は、使用に起因する損害、データの損失、その他の問題について責任を負いません。サードパーティ製ツールを使用する前に、必ず金融データのバックアップを作成してください。

ライセンス

MIT