GnuCash

gnucash-mcp

Claude が GnuCash の帳簿を読み取り、銀行明細をインポートできる MCP サーバーです。 どの銀行の明細 CSV をアップロードしても、Claude がそのレイアウトを把握し、各行のカテゴリを提案してプレビューを表示します。書き込みを行う前に重複を検出します。

2 つの部分で構成されています。

• gnucash_storage：帳簿ごとに設定する piecash のラッパーで、読み取りヘルパーと冪等性のある書き込み機能を備えています。
• gnucash_mcp：stdio 経由でツールとプロンプトを公開する MCP サーバーです。

要件：SQLite 形式の帳簿

GnuCash はデフォルトで帳簿を XML 形式（通常は gzip 圧縮）で保存します。このプロジェクトの基盤である piecash は XML を読み取れません。読み取れるのは GnuCash の SQL 形式のみで、このサーバーは SQLite ファイルを開きます。帳簿を変換するには、次の手順を行います。

1. GnuCash で帳簿を開きます。
2. ファイル > 名前を付けて保存を選択します。
3. データ形式をsqlite3に設定し、ファイル名を指定して保存します。
4. 帳簿の TOML ファイルにある book_path を新しいファイルに設定します。

以降は、GnuCash でも SQLite ファイルを使い続けてください。XML ファイルにはインポートした取引が反映されません。book_path が XML 形式の帳簿を指している場合、すべてのツールはこの変換方法を説明するメッセージを表示して失敗します。

また、uv と Python 3.13 以降が必要です。必要に応じて uv が Python をインストールします。

帳簿を設定する

帳簿用の TOML ファイルを作成します。たとえば、~/gnucash/personal.toml のようにします。

book_path = "personal.gnucash"   # relative to this TOML file, or an absolute path
bank_account = "Assets:Current Assets:Checking Account"  # default bank side for imports
open_if_lock = false             # open for writing even while GnuCash has the file open
do_backup = true                 # piecash writes a timestamped backup before writing

# Optional: "posting" (booking date) or "transaction" (when the purchase happened).
date_source = "posting"

# Optional hints about your bank's statement format, added to the import prompts.
statement_notes = '''
Details holds the merchant and a card reference "REF <12 digits>" (use it as
external_id). The card date inside Details is YY/MM/DD.
'''

必須なのは book_path のみです。

statement_notes には、参照 ID がどこに記載されているか、2 つの日付列のどちらを使うか、見慣れない列が何を意味するかなど、銀行固有の注意事項を記載します。Claude は列の対応付けの際にこのメモを読み取りますが、確認用に対応付けを表示します。これにより、サーバーは特定の銀行に依存せず、各ユーザーの銀行に関する知識はそれぞれの設定ファイルに保存されます。

date_source は、明細に日付が 2 つある場合に、どちらを取引日として使うかを指定します。銀行の計上日（記帳日）か、実際に支払った取引日です。カードの購入は 1、2 日後に計上されることが多く、カード利用日は説明欄にしか記載されていない場合があります。date_source が未設定の場合、明細に両方の日付があると、Claude はインポート時に確認します。設定することをおすすめします。参照 ID のない行では、重複の検出に日付が使われるため、インポートごとに異なる日付を使うと、同じ行が 2 回取り込まれる可能性があります。

インストール

サーバーは uvx で実行するため、システム全体へのインストールは不要です。GNUCASH_MCP_CONFIG に帳簿の TOML ファイルを絶対パスで指定します。

Claude Code：

claude mcp add gnucash -e GNUCASH_MCP_CONFIG=/absolute/path/to/personal.toml -- uvx gnucash-mcp

Claude Desktop： claude_desktop_config.json（macOS では ~/Library/Application Support/Claude/ にあります）に次の内容を追加し、Claude Desktop を再起動します。

{
  "mcpServers": {
    "gnucash": {
      "command": "uvx",
      "args": ["gnucash-mcp"],
      "env": {"GNUCASH_MCP_CONFIG": "/absolute/path/to/personal.toml"}
    }
  }
}

Claude Desktop が uvx を見つけられない場合は、"uvx" をそのフルパス（which uvx）に置き換えてください。

ツールとプロンプト

ツール：

• list_accounts
• get_account(fullname)
• list_transactions(fullname, start_date, end_date, limit)
• create_account(fullname, account_type, currency=None, description="", placeholder=False)：親アカウントが存在している必要があります。通貨のデフォルトは親アカウントの通貨です。
• find_transactions(search, limit=5)：説明、メモ、または番号に検索語が含まれる、すべてのアカウントの取引を新しい順に検索します。
• copy_transaction(guid, post_date, external_id=None, notes=None)：既存の取引のすべてのスプリット（2つを超える場合も含む）をコピーして追加します。新しく指定するのは日付、番号、メモだけです。add_transactionでは書き込めないエントリーに対するクローンオプションで使用します。
• add_transaction(post_date, description, counter_account, amount, account=None, external_id=None, notes=None, force=False, quantity=None)
• update_transaction(guid, post_date=None, description=None, external_id=None, notes=None, counter_account=None, amount=None, account=None, quantity=None)：既存の取引を変更します。省略したフィールドはそのまま残り、空のexternal_idまたはnotesを指定するとクリアされます。guidはlist_transactionsで取得します。amount、quantity、またはcounter_accountを変更するには、2つのスプリットを持つ取引が必要です。両方のスプリットが移動するため、取引の均衡は保たれます。account（デフォルト：設定のbank_account）は、amountがどちら側を指すかを指定します。商品アカウントを相手勘定とする取引でamountだけを変更した場合、単位数はそのままで価格が変わります。コピーの金額を変更するには、copy_transactionが返すguidを指定してこのツールを呼び出します。
• delete_transaction(guid)：取引とそのスプリットを完全に削除し、削除した内容を返します。
• reconcile_transactions(guids | start_date/end_date, state="y", account, dry_run=True)：GUIDまたは転記日付の範囲（両端を含む）で選んだアカウントのスプリットに、照合状態（yは照合済み、cは消し込み済み、nは未照合）を設定します。変更されるのはaccount上のスプリットだけです。ドライランでは、変更されるスプリット数とその日付範囲が報告されます。書き込みは一度に保存されるため、GnuCashの照合ウィンドウを使う必要はありません。
• import_transactions(rows, dry_run=True)：一括インポートします。各行にはnew、added、duplicateのいずれかのステータスが割り当てられ、重複行には一致した既存の取引が含まれます。

accountを省略した場合は、設定のbank_accountがデフォルトで使用されます。読み取りツールとドライランでは、帳簿を読み取り専用で開きます。書き込みでは、書き込み用に開きます。一括インポートでは帳簿を一度だけ開くため、バックアップファイルは1つ作成されます。

プロンプト：

• import_bank_statement：プレビュー表を表示し、一度の一括書き込みで銀行のCSVをインポートします（Claude Codeでは、/mcp__gnucash__import_bank_statementを実行します）。
• review_bank_statement：銀行のCSVを1行ずつインポートし、各行について判断を待ちます（Claude Codeでは、/mcp__gnucash__review_bank_statementを実行します）。
• clone_transaction：検索語を尋ね、最も新しい類似エントリーを検索します。日付と金額を確認した後、同じアカウントと説明で新しいエントリーを追加します（Claude Codeでは、/mcp__gnucash__clone_transactionを実行します）。

商品（ゴールド、株式）の購入

相手勘定がゴールドコインや株式などの非通貨商品を保有する場合は、購入または売却した単位数を正の数でquantityに指定します。amountは銀行口座の通貨での金額のままで、1単位あたりの価格はamount / quantityです。取引では銀行口座の通貨が維持されます。銀行側のスプリットには-amountが設定され、相手側のスプリットには値-amountと数量quantityが設定されます（amountが正の売却では負の値になります）。

add_transaction(
    post_date=date(2026, 9, 29),
    description="Buy 5 from Anis",
    counter_account="Assets:Gold English Coins 21 carat",  # commodity XGL21-8
    amount=Decimal("-3330"),                               # JOD out of the bank
    quantity=Decimal("5"),                                 # 666 JOD per coin
    account="Assets:Bank Accounts:ArabBank Jordan",        # commodity JOD
)

このような相手勘定にはquantityが必須です。銀行口座の通貨を使用する相手勘定には指定できません。値は正で、商品の端数単位より細かくすることはできません。import_transactionsの行でも同じquantityフィールドを使用します。2つの通貨間の換算には、引き続き対応していません。

銀行取引明細のインポート

1. CSV をアップロードし、import_bank_statement プロンプトを実行します。
2. Claude は、銀行を問わず、ヘッダーと最初の数行から CSV のレイアウト（区切り文字、日付列と日付形式、説明列、金額）を判断します。符号付きの金額列が 1 つの場合と、出金列と入金列が別々の場合の両方に対応し、小数点の表記（1,234.56 または 1.234,56）もどちらも扱えます。解析した 1 行を使って列の対応関係を表示し、すべての行を解析する前に確認を待ちます。出金額は負の金額に、入金額は正の金額になります。各行には短く読みやすい説明（例：Zalatimo Sweets）が付き、銀行の元のテキストは取引のメモにそのまま保持されます。Claude はファイルの先頭に最新の行が記載されているかを確認し、そうであれば下から上に読み込み、銀行独自の順序のまま古い行から書き込みます（同日の行は並べ替えません）。銀行のテキストを説明としてそのまま使用したい場合は、列の対応関係を確認する際に伝えてください。その後、Claude が各行のカテゴリ口座を選択します。
3. Claude は import_transactions(rows, dry_run=True) を呼び出し、各行に新規または重複の印を付けたプレビューを表示します。
4. 確認後、Claude は import_transactions(rows, dry_run=False) を呼び出します。新しい行はまとめて書き込まれ、重複行は除外されます。
5. 重複行ごとに、Claude は強制的に登録するかスキップするかを尋ねます。強制する場合は add_transaction(..., force=True) を呼び出します。たとえば、同じ日に実際に同一の買い物を 2 回した場合に対応できます。

各取引は銀行口座固有の通貨で記録されるため、USD の帳簿にある EUR 口座の取引は EUR で記録されます。通貨換算には対応していないため、カテゴリ口座も同じ通貨である必要があります。使いたいカテゴリがない場合、Claude は create_account での作成を提案し、確認後に作成します。

いずれかの行に不明な口座がある場合、通貨が混在している場合、または金額の小数桁数が銀行口座の通貨で許容される桁数を超える場合、何も書き込まれません。

行ごとに確認する

代わりに review_bank_statement を実行します。同じ通貨確認、解析、カテゴリ選択の手順の後、Claude は 1 行ずつ（Row i/N）表示します。各行には、Num（取引番号として保存される銀行の参照番号）、提案されたカテゴリ、新規か重複かが示されます。各行について、次のいずれかを選択します。

• 承認： import_transactions([row], dry_run=False) で、その行をただちに書き込みます。
• 変更： カテゴリ、説明、金額を編集してから、行を再度確認します。
• スキップ： 何も書き込みません。
• 強制： 重複行のみ。add_transaction(..., force=True) で、その行を登録します。
• 残りをすべて承認： 残りの新しい行をまとめて書き込みます。重複行は引き続き 1 行ずつ確認します。
• 停止： 確認を終了し、概要を表示します。

承認した行はただちに書き込まれます。途中で停止しても、書き込み済みの行は帳簿に残り、再実行すると重複として表示されます。承認ごとに個別に書き込まれるため、do_backup = true の場合、承認した行ごとにバックアップファイルが作成されます。バックアップが不要な場合は、帳簿の TOML で do_backup = false に設定してください。

冪等性のある書き込み

from decimal import Decimal
from datetime import date
from pathlib import Path
from gnucash_storage import (
    NewTransaction,
    add_transaction,
    load_config,
    open_configured_book,
)

config = load_config(Path("books/development-book.toml"))
with open_configured_book(config, readonly=False) as book:
    added = add_transaction(
        book,
        NewTransaction(
            post_date=date(2025, 11, 28),
            description="TEST BISTRO REST.",
            account="Assets:Current Assets:Savings Account",
            counter_account="Expenses:Dining",
            amount=Decimal("-36.00"),  # money out of the bank account
        ),
        force=False,  # set force=True to bypass duplicate checking
    )

行には、任意の external_id を指定できます。これは、カードの取引参照番号（REF 606006000101）、OFX の FITID、銀行の参照番号など、銀行から付与される一意の参照情報です。これは取引の Num フィールドに保存されます。インポート時に Claude はこのような参照情報を探し、確認する列マッピングに含めます。

同じ銀行口座にある既存の取引は、次のいずれかに該当する場合、重複として扱われます。

• 日付や説明にかかわらず、同じ external_id を持つ場合。これにより、エクスポートのたびに銀行が説明を整形し直しても、二重にインポートされません。または
• 入金日、銀行のテキスト、金額（口座の通貨）が同じ場合。ただし、両方に ID があり、その値が異なる場合を除きます。同じ日に行われた同額の購入でも、カード参照番号が異なれば両方がインポートされ、ID が使われる前に追加された取引も引き続き認識されます。

銀行のテキストとは、取引のメモ、またはメモがない場合は説明を指します。整形済みの説明ではなく銀行独自のテキストで照合するため、後のインポートで説明の表現が異なっていても重複として扱われます。メモが使われる前にインポートされ、銀行のテキストが説明として保存されている取引も照合されます。

force=False（デフォルト）の場合、add_transaction は重複を追加せず、False を返します。重複チェックを回避して強制的に挿入するには、force=True を渡します。

GnuCash の Use Split Action Field for Number オプションが有効な場合、登録簿の Num 列には分割アクションが表示されます。参照情報は引き続き取引に保存されます。

開発

サーバー自体に必要なのは mcp と piecash のみです。開発ツールとノートブックライブラリはオプションの追加機能です。

uv sync --extra dev                    # tests, ruff, mypy
uv sync --extra dev --extra notebooks  # plus marimo, Jupyter, polars, pandas, openai

チェックアウトからサーバーを実行します。

GNUCASH_MCP_CONFIG=books/example.toml uv run gnucash-mcp

このリポジトリでは、.mcp.json に books/development-book.toml を使用するサーバーが、Claude Code 用に gnucash としてすでに登録されています。Claude Code からプロンプトが表示されたら承認し、claude mcp get gnucash で確認します。

ノートブック

ノートブックには notebooks エクストラが必要です（uv sync --extra notebooks）。

Marimo のノートブックサーバー／エディターを起動します。

uv run marimo edit notebooks/

または、ノートブックを読み取り専用のアプリモードで実行します。

uv run marimo run notebooks/gnucash_exploration.py

notebooks/statement_mapping.py は、notebooks/samples/ にある 2 つのサンプル明細を使って、汎用 CSV マッピングを確認します。

• us_signed_amount.csv：カンマ区切り、米国式の日付、符号付きの Amount 列 1 つ
• eu_debit_credit.csv：セミコロン区切り、ドイツ語のヘッダー、dd.mm.yyyy 形式の日付、独立した Soll/Haben 列、小数点としてのカンマ

各サンプルについて、ノートブックは Claude が確認するマッピングを適用し、使い捨ての帳簿に行をインポートします。その後、符号と残高を確認し、2 回目のインポートですべての行が重複として報告されることを確認します。

uv run marimo edit notebooks/statement_mapping.py

チェック

uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy src

各 git push の前に CI と同じチェックを実行するには、クローンごとに 1 回、追跡対象の pre-push フックを有効にします。

git config core.hooksPath .githooks

1 回だけフックをスキップするには、git push --no-verify を使用します。

リリース

リリースは、信頼された公開を利用して .github/workflows/publish.yml から PyPI に公開されるため、API トークンは必要ありません。

PyPI での初回セットアップ：Your account > Publishing > Add a new pending publisher に移動し、次のように入力します。

フィールド	値
PyPI プロジェクト名	gnucash-mcp
オーナー	tillawy
リポジトリ名	gnucash-mcp
ワークフロー名	publish.yml
環境名	pypi

リリースするには：

1. pyproject.toml の version を更新してから、コミットしてプッシュします。

2. タグがそのバージョンに v を付けた値になるよう、GitHub リリースを作成します。

   gh release create v0.1.0 --generate-notes
   

ワークフローはタグがバージョンと一致することを確認し、テスト、ruff、mypy を実行して、パッケージをビルドし、アップロードします。アップロードのたびに手動承認を必須にするには、Settings > Environments の pypi 環境に必須レビュアーを追加します。

公開せずにローカルでビルドを確認するには：

uv build
uvx twine check --strict dist/*