gnucash-mcp

gnucash-mcp

LLM と連携する、無料のオープンソース会計ソフトウェアです。

Claude（または MCP に対応する任意の AI アシスタント）を通じて、GnuCash の帳簿に話しかけましょう。「今月の家計はどう？」と尋ねたり、取引を声に出して記録したり、暮らしや仕事に集中している間、帳簿の管理を AI に任せたりできます。

サーバーはお使いのマシン上で動作し、ローカルの GnuCash ファイルを使います。ファイルと監査ログが外部に送信されることはありません。AI アシスタントに見えるのは、画面で確認するのと同じように、ツール呼び出しの結果（残高、支払先、請求書）です。

1.4 からアップグレードする場合は、1.5 で最初に書き込みを行う前に、アップグレードガイドをお読みください。

ワンクリックでインストール： Claude Desktop では、最新リリースから.mcpbバンドルをダウンロードしてダブルクリックすれば、すぐに使い始められます。ターミナルも設定ファイルも不要です。それ以外の MCP クライアント（ChatGPT/Codex、Gemini、Antigravity など）は、数行の設定で接続できます。どちらの方法でも、すでに利用中の AI サブスクリプションが、請求書を送ってこない帳簿係になります。

すぐに試せる、現実的なサンプル帳簿が3つあります。丸一年分の取引、複数通貨、顧客、請求書、予算が含まれています。Claude Desktop のバンドルにはサンプル帳簿が含まれています。リポジトリをクローンした場合は、コマンド1つで作成できます。5分で試してみて、気に入ったらサーバーを自分の帳簿に向けるだけで準備完了です。

---

どんな画面ですか？

サンプル帳簿を開くと、AI アシスタントには次のように表示されます。1回の呼び出しで、財務状況をすべて確認できます。

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

これはスクリーンショットではありません。AI が実際に受け取る概要画面です。純資産の推移、資金が持つ期間、予算の進捗状況、未払いの相手、期限超過の項目、未照合の項目がわかります。1回呼び出すだけで、あなたが挨拶を終える前に、アシスタントは全体像を把握できます。

---

どんな人に向いていますか？

• GnuCash で帳簿をつけている個人の家計管理ユーザー： 取引を口述で記録したり、アシスタントにお金の使い道を尋ねたり、照合を手伝ってもらったり、予算を計画したりできます。
• GnuCash で帳簿をつけている小規模事業者： 会話を離れずに、請求書の発行、売掛金の管理、仕入先への支出の確認、キャッシュフローの管理ができます。
• データをローカルに保管したい人： クラウド同期も SaaS もありません。.gnucashファイルが正式な記録元です。このツールを使うと、GnuCash 自身と同じ方法で、AI がそのデータを読み書きできるようになります。

開発者である必要はありません。必要なものは次のとおりです。

• コンピューター（Mac、Windows、または Linux）
• GnuCash 本体、またはインストールする意思（gnucash.orgから無料で入手できます）
• MCP に対応する AI アシスタント（最も一般的なのは Claude Desktop です。Claude Code、Continue.dev なども利用できます）
• サンプル帳簿を動かすのに10分、さらに自分の帳簿に接続するのに10分

---

リスクなしで試す

このリポジトリには、実際のデータに触れずに試せる、架空の帳簿を使った3つのサンプル人物像が含まれています。バンドルにはビルド済みの帳簿が含まれています。リポジトリをクローンした場合は、コマンド1つで作成できます。1つ選んでサーバーをその帳簿に向け、質問を始めてください。

samples/alex-chen-morales.gnucash — 個人＋フリーランス

シアトル在住の独立系ソフトウェア請負業者で、単独出資の LLC を運営し、配偶者は病院勤務です。デフォルト通貨は USD です。111個の勘定科目があり、2025年からビルド日までの取引が2,000件以上あります。住宅ローン、VTSAX/VBTLX/AAPL/MSFT/ETH を保有する証券口座、配偶者の403(b)に加えて Solo 401(k)、USD・EUR・CAD で請求する8社の顧客、買掛金経由で請求する下請業者、ワシントン州の B&O 税、定期請求、予算など、サーバーでできることのほぼすべてが1つの帳簿に含まれています。

samples/lin-wei.gnucash — 深圳のソフトウェアスタジオ

登録済みの個人事業スタジオを経営し、越境ECソフトウェアを開発する深圳の開発者と、病院から給与を受け取る配偶者。通貨の既定値はCNYで、ネイティブのzh_CN勘定科目表を使用します。勘定科目は101件、取引は約3,000件です。Tencent、DJI、SF Techなどの深圳のテック企業のクライアントからCNYで入金があり、USD/EURのクライアントからは外貨で入金され、為替レートの変動による実現為替差損益が発生します。国内の中国株投資（宁德时代と2つのETF）、パートタイム従業員、HKD建てクレジットカード、住宅ローンがあり、法人銀行口座、Alipay、WeChat Payを併用しています。

samples/sabine-brenner.gnucash — ドイツのフリーランス、SKR03勘定科目表

ミュンヘンを拠点とするフリーランスのデザイナーです。通貨の既定値はEURで、ドイツのSKR03勘定科目表を使用しており、すべての勘定科目名がドイツ語です。勘定科目は125件、取引は約1,900件で、VAT申告が稼働中であり、1％ルールに基づく社用車もあります。英語の勘定科目名やUSDを前提とする機能があれば、Sabineの帳簿で問題が発生します。

3つの帳簿はすべて架空のものです。それぞれの内容の詳細は、samples/README.mdをご覧ください。

---

クイックスタート

ワンクリックでインストール（Claude Desktop）

最新リリースから**.mcpbバンドル**をダウンロードして、ダブルクリックしてください。Claude Desktopがサーバーをインストールします。ターミナルも設定ファイルもPythonも必要ありません。インストーラーで次の3項目を指定します。

• GnuCashの帳簿 — ファイル選択ダイアログが表示されます。帳簿はSQLite形式である必要があります。古いXML形式の場合は、まず一度だけ形式を変換してください。複数の帳簿を選ぶと、チャット内で切り替えられます。
• デモ用帳簿 — チェックボックスを1つ選ぶと、上記の3つのサンプル帳簿を利用できます。自分の帳簿を接続する前、または接続せずに、架空のお金を使って試せます。
• 「クライアントに請求書を発行しますか？」 — 「はい」を選ぶと、ビジネス向け機能一式（顧客への請求書、ベンダーからの請求書、従業員経費）が追加されます。それ以外の機能（予算、定期取引、投資追跡など）は常に有効です。

インストールはこれで完了です。

試してみる

Claudeに次のように尋ねてください。

• 「帳簿の概要をまとめて。」
• 「純資産はどう推移している？」
• 「私にお金を借りている人を見せて。」
• 「先月、外食にいくら使った？」
• 「毎月500ドルの食料品予算を設定して。」

最初の回答では通常、上記のダッシュボードが表示されます。その後はすべて会話形式で操作できます。

自分の帳簿を使う準備ができたら、以下の自分の帳簿を接続するをご覧ください。

その他のAIクライアント、またはソースからインストールする場合

ChatGPTとCodex、Claude Code、Gemini CLI、Google Antigravity、およびその他のMCPクライアントは、Gitクローンからのインストールを通じて接続します。データベース形式の帳簿を使う場合や、サーバーの開発に携わる場合も同様です。詳しくはdocs/CLIENTS.mdをご覧ください。

---

自分の帳簿を接続する

一度だけ行う変換：GnuCashのファイル形式

このサーバーが読み取れるのは、GnuCashファイルのSQLite形式のみです。古いXML形式には対応していません。変換手順は次のとおりです。

1. GnuCashで帳簿を開きます
2. ファイル → 名前を付けて保存
3. 「データ形式」をSQLite3に変更します
4. 新しいファイル名（例：mybook-sqlite.gnucash）で保存します
5. 元のXMLファイルはバックアップとして残してください。

Linux（Debian/Ubuntu）の場合、「データ形式」ドロップダウンにSQLite3が表示されないことがあります。GnuCashにはバックエンドドライバーが必要ですが、既定ではインストールされていません。GnuCashを閉じてドライバーをインストールし、その後GnuCashを再度開くと、オプションが表示されます。

sudo apt update && sudo apt install libdbd-sqlite3

この操作は一度だけ行えば大丈夫です。以降はGnuCashとMCPサーバーの両方が同じSQLiteファイルを使用します。

**GnuCash 3.8以降が必要です。**サーバーが帳簿に書き込むと、GnuCash 3.8で導入された機能マーカー（「予算金額で自然符号を使用」）が帳簿に付与されます。GnuCash 3.0～3.7は、認識できない機能のマーカーが付いた帳簿を開けません。GnuCash 3.8以降も、予算のある帳簿を開くと同じマーカーを付与するため、これは古い3.xを使い続けている場合にのみ関係します。このサーバーはGnuCash 5.12でテストされています。

サーバーの参照先を設定する

バンドルを使う場合は、Claude Desktop の GnuCash 拡張機能の設定で帳簿を選択し、Claude Desktop を再起動します。クローンからインストールする場合は、GNUCASH_BOOK_PATH に帳簿の絶対パスを設定します。自分の帳簿を使うを参照してください。

または：帳簿を PostgreSQL または MySQL に保存する

GnuCash では、帳簿をファイルではなくデータベースに保存することもでき、サーバーはその帳簿も提供できます。パスではなく、接続文字列を指定します。

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

サーバーと一緒にドライバー（postgres または mysql。MariaDB も同じドライバーを使います）をインストールします。クローンの中（gnucash-mcp フォルダー。ソースからのインストールを参照）で、次のコマンドを実行します。

uv tool install -e ".[postgres]" --reinstall

MySQL / MariaDB の場合、接続文字列は mysql+pymysql://user:password@localhost:3306/gnucashで、追加機能は [mysql]です。uv tool install -e ".[mysql]" --reinstallを実行します。 GnuCash 自身が出力する短縮形のmysql://とpostgres://も使えます。サーバーは追加機能でインストールされたドライバーを使用します。

前述のとおり、名前を指定するのではなく、クローンからインストールしてください。PyPI のgnucash-mcpという名前は別のプロジェクトが使用しています。

既存の帳簿を移行するには、GnuCash で帳簿を開き、 ファイル → 名前を付けて保存を選択し、postgresまたはmysqlを選んで、接続情報を入力します。（Debian/Ubuntu では、SQLite3 にlibdbd-sqlite3が必要なのと同じように、これらの項目を使うにはsudo apt install libdbd-pgsqlまたはlibdbd-mysqlが必要です。macOS と Windows のビルドには、3 つすべてが同梱されています。） ファイルは残しておいてください。切り替えた時点までの内容をすべて保存した、完全なバックアップとして使えます。

切り替える前に知っておくべきこと：

• GNUCASH_BOOK_PATHとGNUCASH_BOOK_URIは同時に設定できません。帳簿はファイルかデータベースのどちらかです。両方を設定すると、書き込み先の台帳がどちらになるか運任せになるのではなく、起動エラーになります。
• GNUCASH_LOG_DIRの設定が必須になります。 監査ログとデバッグログは通常、帳簿ファイルの隣のフォルダーに保存されますが、接続文字列には「隣」がありません。
• サーバーごとに帳簿は 1 つです。 switch_bookはファイル名で照合するため、複数の帳簿を扱えるのはファイルを使う場合に限られます。
• サーバーによるバックアップは停止します。 これが実際に伴うトレードオフです。自動バックアップがあるのはファイルのスナップショットを作成できるためであり、データベースのスナップショットは作成できません。create_backupは、できるふりをせず、その旨を伝えます。実際の帳簿を移行する前に、pg_dumpまたはmysqldumpを定期実行するよう設定してください。docs/RESTORE_FROM_BACKUP.mdを参照してください。
• サーバーが帳簿を示す際には、ツールの結果、ダッシュボードのヘッダー、監査ログのいずれでも、パスワードはマスクされます。また、データベースドライバーが出力するものも含め、すべてのエラーメッセージ、ログ行、起動エラーでもマスクされます。クエリパラメーター（?password=…、sslpassword=…）で指定したパスワードも同様にマスクされます。
• 接続文字列はコマンドラインではなく、envブロックに記述してください。 --book-uriも使えますが、コマンドラインに記述したパスワードは、プロセス一覧を見られるマシン上のすべてのユーザーに表示されます。PostgreSQL では、接続文字列からパスワードを完全に省略して、ドライバーにPGPASSWORDまたは~/.pgpassを読み込ませることもできます。

テストスイートと CI では、どちらの方式も実際のサーバーを使って検証しています。PostgreSQL 16 と MariaDB 11 が対象です。

---

モジュールセットの選択

--modules=all は手軽なデフォルト設定です。すべてのツール、計86個が含まれます。 日常的な利用では、おそらくもっと少ない数が必要でしょう。サーバーとのやり取りの方法に合った役割を選んでください。より細かく選びたい場合は、各役割に含まれるモジュールを個別に選択することもできます。

役割	含まれる機能	ツール
core	台帳の基本機能 — 勘定科目、取引、残高、スロット、監査ログ、バックアップ、貸借対照表、照合。常に読み込まれます。	29
bookkeeper	ビジネス機能を除くすべての機能：レポート、予算、予定取引、価格、投資ロット。個人向け家計管理のセットです。	30
investor	取得原価の追跡と価格管理のみ（bookkeeper の一部）。	13
business	顧客、仕入先、従業員、請求書、請求、伝票、クレジットノート、売上税、支払条件、ジョブ、仕入先レポート。	27

1つ以上をカンマ区切りで選択します。

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

core は常に追加されます。1.4 で使われていた freelancer と business_complete も引き続き使用でき、どちらも business を意味します。各役割のモジュール（reconciliation、reporting、budgets、scheduling、tax_lots、portfolio など）も個別に選択できます。すべての選択肢を確認するには、リポジトリから uv run gnucash-mcp --help を実行してください。

---

どんなことを頼めるか

ここでは一部をご紹介します。以下のようなことを自然な言葉で伝えれば、アシスタントが対応します。

明細書全体を入力する

「8月の当座預金口座の明細書です。」（PDF を添付）

帳簿の31行と照合しました：新規24件、入力済み（確認済み）6件、確認が必要なもの1件です。比較結果はこちらです。 確認していただければ、今月分を入力してカテゴリ分けし、期末残高まで一度に照合します。

明細書1通、呼び出し2回、帳簿の残高が一致します。ドライランでは書き込みを行う前に、証拠を示しながら各行を分類します。また、残高が一致しない月をそのまま登録しないよう、確定処理では一括登録を拒否します。

取引を記録する

「今日、Safeway で食料品に $47.50 使いました。Visa で支払いました。」

2026年4月30日付で、Credit Card:Visa から Expenses:Groceries に $47.50 を記録しました。説明：「Safeway」。

定期的な請求を設定する

「家賃を定期的な請求として設定してください。毎月1日に、当座預金口座から $1,850 です。」

予定取引「Monthly Rent」を作成しました：Assets:Checking から Expenses:Rent に毎月 $1,850。次回支払期日：2026年5月1日。

投資を追跡する

「401(k) で VTSAX を1,000ドル分、1株あたり $170.99 で購入しました。」

VTSAX の購入を記録しました：1株あたり $170.99 で5.85株。取得原価：$1,000.00。将来売却する際の譲渡益追跡用にロットを作成しました。

顧客に請求書を発行する

「Acme Corp という顧客を作成し、コンサルティング料 $1,500 の請求書を発行してください。」

顧客 Acme Corp（id 000005）と請求書 000019 を作成しました： 1× コンサルティング、$1,500.00 = $1,500.00。未記帳です。記帳する準備ができたらお知らせください。

サーバーで記帳した請求書を GnuCash の「支払い処理」ダイアログで開く場合は、最初に「転記先」勘定科目として請求書の売掛金勘定を設定してください。このダイアログには、選択した勘定科目に転記された書類だけが表示されます。

外貨建ての請求書を発行する

「Berlin Digital に、第1四半期のリテイナー料として €4,200 の請求書を発行してください。支払期限は30日後です。」

Berlin Digital GmbH 宛てに EUR 建ての請求書 000020 を作成しました： 1× 第1四半期リテイナー料、EUR 4,200 = EUR 4,200。支払期限は30日後です。支払いを受けたときは、実現した為替差損益を FX 勘定に自動的に記帳します。

質問する

「今年、仕入先ごとにいくら使いましたか？」

Office Depot：$2,340（請求4件、未払い $0） CloudHost Inc：$1,200（請求2件、未払い $600） Legal Associates：$3,500（請求1件、未払い $3,500） 請求総額 $7,040／支払済み $2,940／未払い $4,100。

照合

「4月の明細書と当座預金口座の照合を手伝ってください。」

（未照合の分割取引を取得し、決済済みの取引を確認するよう案内します。残高の推移を計算し、一致した取引を照合済みにし、不一致は調査用に残します。）

---

プライバシーと安全性

書籍ファイルがマシンの外に出ることはありません。 このサーバーは、ローカルファイルを読み書きするローカルプロセスです。やり取りしている AI アシスタント（Claude Desktop など）には、ツール呼び出しの結果、つまり画面に表示されるものと同じ内容が見えますが、ファイル自体は常に元の場所にあります。

すべての書き込みが記録されます。 人が読める監査ログは、書籍ファイルと同じ場所にある <your-book>.gnucash.mcp/audit/ に保存され、1 日につき 1 つのログファイルが作成されます。いつでも読んで、何がいつ変更されたかを正確に確認できます。ログの例：

2026-04-30 14:32  POST INVOICE  id:000019
    total: 1500.00  date: 2026-04-30
    account: Assets:Accounts Receivable  txn:a1b2c3d4

自動バックアップ。 各セッションの最初の書き込みの前に（また、長時間のセッションが新しいバックアップ期間に入る際にも）、サーバーは書籍のスナップショットを <your-book>.gnucash.mcp/backups/ に保存します。問題が起きても、Time Machine や自分の習慣に頼らず、正常な状態に戻せます。バックアップは有効と見なされる前に PRAGMA integrity_check で検証され、前回のスナップショット以降に書籍が変更されていない場合は作成されません。ロールバックの手順については、docs/RESTORE_FROM_BACKUP.md を参照してください。

タイムスタンプについて： バックアップの ファイル名 には UTC タイムスタンプが含まれます（ファイルシステムで安全に扱え、移動中や夏時間の切り替え時にも曖昧になりません）。監査ログとデバッグログには、日付が ローカル時間 の日次ファイルが使われます。「火曜日に何が起きたか」を検索する方法に合わせたものです。真夜中の前後では日付が 1 日ずれることがあるため、バックアップとその日のログを照合する際はご注意ください。

照合済みの分割は保護されます。 サーバーは明示的な上書きがない限り、照合済みの分割の削除や変更を拒否します。そのため、不注意なプロンプトによって直近の銀行照合が知らないうちに無効になることはありません。

無効化 ≠ 削除。 AI に「この取引を無効化して」と指示すると、GnuCash の正式な会計上の無効化処理を行います。値をゼロにして監査ログ用に取引を保持します。削除は破壊的な操作であり、AI はどちらを実行するかを伝えます。

免責事項： 本ソフトウェアは、いかなる種類の保証もなく、MIT License に基づいて「現状のまま」提供されます。作者は、本ソフトウェアの使用に起因するデータの損失や破損、または財務上の不一致について責任を負いません。ご自身のバックアップを維持し、帳簿の正確性を確認する責任は、すべて利用者にあります。

---

既知の制限事項

• GnuCash デスクトップとサーバーの両方で、同時に編集しないでください。 サーバーは GnuCash のロックを尊重しますが、独自のロックは保持しません（1 回の呼び出しごとに書籍を開きます）。そのため、サーバーが書籍を使用中であることを GnuCash が警告しません。
• 「Use Trading Accounts」が有効な書籍： 株式やファンドの購入を含む、通貨や商品をまたぐ取引は拒否されます。サーバーはまだ GnuCash と同じ方法で取引分割を書き込めないためです。これらは GnuCash デスクトップで入力してください。単一通貨での操作は通常どおり行えます。
• GnuCash 3.8 以降が必要です。 サーバーが書き込みを行った書籍には機能マーカーが付与されるため、GnuCash 3.0～3.7 では開けません。
• 外貨建ての支出と収入は、支出・収入レポートでは支払いに使った現金ではなく、各月の月末レートで評価されます。現金については cash_flow がレポートします。

完全な一覧は CHANGELOG.md にあります。

---

AI が参照できる範囲を制限する

各ツールの説明は AI のシステムプロンプトに含まれ、メッセージごとにコンテキストを消費します。実際に使うツールセットに絞ることで、すべての会話にかかるコストを抑えられます。4 つの役割（core、bookkeeper、investor、business）については、上記のモジュールセットの選択を参照してください。

JSON の引数で --modules=... を指定する代わりに、環境変数として GNUCASH_MCP_MODULES=core,bookkeeper を設定することもできます。

---

v1.5.0 の新機能

• データベース内の帳簿。 サーバーを、SQLite ファイルだけでなく、GnuCash が PostgreSQL または MySQL/MariaDB で管理する帳簿に接続できます。詳しくはまたは、帳簿を PostgreSQL または MySQL に置くをご覧ください。 PostgreSQL のサポートは @vchatela による貢献です。
• すべて GnuCash デスクトップと同じ方法で保存されます。 定期取引はデスクトップの「前回以降の取引を実行」で処理され、予算、 請求書、クレジットノート、無効化、価格はどちらでも同じように読み込まれます。また、請求書の合計は GnuCash 独自の計算とセント単位まで一致します。1.4 からアップグレードしますか？まずアップグレードガイドをお読みください。
• 前受金。 顧客または仕入先の過払い金を預かり金として記録し、 後日、その金額を請求書の支払いに充当できます。また、支払いを失わずに、支払い済み請求書の転記を解除できます。
• すべての取引ツールに番号と書類へのリンクを追加し、 番号を重複チェックに使用します。
• ダッシュボードに勘定科目一覧のマップを表示し、 アシスタントが質問する前に各勘定科目の場所を把握できます。
• ソースから作成したサンプル帳簿。それぞれ、対象国の税務慣行（米国／ワシントン州、ドイツ、中国）に照らして検証され、 作成日における最新の状態になっています。

以前のリリースについてはCHANGELOG.mdをご覧ください。

---

トラブルシューティング

🔨 ハンマーアイコンが表示されない、または「tool not found」と表示される

• Claude Desktop を完全に終了してから、再度開いてください。（ウィンドウを閉じるだけでは不十分です。アプリケーションを終了する必要があります。）
• 設定内のパスが絶対パスで、正しいことを確認してください。
• JSON に末尾のカンマがないか確認してください。設定がエラーを表示せずに壊れる原因になります。

「Book not found」と表示される

• ~ や相対パスではなく、絶対パスを使用してください。
• Mac/Linux：/Users/yourname/Documents/book.gnucash
• Windows：C:\\Users\\yourname\\Documents\\book.gnucash （バックスラッシュを 2 つにします。JSON の要件です）

「Cannot open book」／piecash のエラー

• 帳簿が XML 形式ではなく、SQLite 形式であることを確認してください。
• GnuCash で同じ帳簿を開いていないことを確認してください。ファイルロックが発生します。 サーバーは GnuCash のロックを尊重しますが、独自のロックは意図的に取得しません（帳簿を保持するのは 1 回の呼び出しの間だけです）。そのため、サーバーが使用中の帳簿を GnuCash で開いても警告は表示されません。両方で同時に編集しないでください。
• 帳簿が破損していないことを確かめるため、GnuCash 自体で開いてみてください。

Docker：「both GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are set」

イメージには、バンドルされたデモ用帳簿を指す GNUCASH_BOOK_PATH が設定されています。データベースの帳簿を使うには、コマンドラインでそのデフォルト値を消去し（-e GNUCASH_BOOK_PATH=）、GNUCASH_BOOK_URI と併せて指定してください。マウントしたファイルを使うには、GNUCASH_BOOK_PATH にマウント先のパスを設定し、ファイルの所有者としてコンテナを実行してください（--user "$(id -u):$(id -g)"）。

「Account not found」と表示される

• Expenses:Groceries のように、勘定科目の完全なパスを指定してください。Groceries だけでは見つかりません。
• または、アシスタントに勘定科目の一覧を依頼してください：「勘定科目を一覧表示して。」

クライアントの再起動後に複数のサーバープロセスが起動する

Claude Desktop（および一部の他の MCP クライアント）は、再起動時にサーバーのコピーを一時的に 2、3 個起動することがあります。これはクライアント側の動作であり、サーバーのバグではありません。また、ほとんどの場合、問題はありません。サーバーはリクエストごとに帳簿を開き、呼び出しの間はファイルロックを解放するため、プロセスが重なるのは一瞬だけです。クライアントの再起動後も Lock on the file エラーが続く場合は、クライアントを完全に終了し、pgrep -fl gnucash-mcp で残存プロセスがないことを確認してから、再起動してください。

問題が発生した場合

• <your-book>.gnucash.mcp/audit/ にある監査ログを開いてください。サーバーを最初に起動してからのすべての書き込みが、変更前後の詳細とともに記録されています。
• ロールバックが必要な場合は、docs/RESTORE_FROM_BACKUP.mdで手順を説明しています。

---

プロジェクトを支援する

gnucash-mcp が役に立った場合は、 コーヒーをおごることをご検討ください。開発の継続に役立ちます。

---

開発者向け

コントリビューターガイドと設計メモは CLAUDE.md にあります。簡単な概要：

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

インストール済みの gnucash-mcp コマンドは、クローンの状態をリアルタイムで反映します。チェックアウト中のブランチにあるコードをそのまま提供するため、ブランチを切り替えると、次回の再起動時に提供するコードも切り替わります。テストには便利ですが、ブランチの途中にいることを忘れたときには注意が必要です。インストールに影響を与えずに別のチェックアウト（2つ目のワークツリー）を実行するには、uv run --directory PATH gnucash-mcp を使うと、指定したディレクトリを実行できます。

サーバーは GnuCash の SQLite 帳簿用 Python インターフェースである piecash と MCP Python SDK を基盤に構築されています。 Python ソースコードは約 18,000 行、テストは 20,000 行で、無効化されたモジュールは実行時にコストがかからないよう、モジュール化されています。

ライセンス

MIT。

謝辞

• GnuCash — このサーバーが会話形式で利用できるようにする、無料のオープンソース会計ソフトウェアです。
• piecash — GnuCash の SQLite 帳簿用 Python インターフェースです。
• MCP Python SDK — Model Context Protocol の実装です。