AIアシスタントに、先月の支出額、照合が必要な口座、取引の分類先を質問してみましょう。Beancount MCPは、ホストされた元帳のクエリ、口座、ソースファイルへのアクセスを提供するため、アシスタントは帳簿に基づいて作業し、その回答の根拠を示すことができます。
書き込み権限があれば、アシスタントは取引の追加や元帳ファイルの更新も行えます。サポートされている編集のプレビューを依頼し、提案されたエントリを確認し、変更後に元帳をチェックすることができます。
MCPはModel Context Protocol（モデルコンテキストプロトコル）の略で、AIアプリケーションを外部ツールやデータに接続するための標準規格です。この接続は、Beancount.ioでホストされている元帳で機能します。アシスタントの回答は、そこに記録された取引と価格を反映します。MCPを接続しても、それらの記録が自動的に最新になるわけではありません。
AIクライアントを接続する
Streamable HTTPを介したリモートMCPをサポートするクライアントを使用してください。サーバーURLは次のとおりです:
https://beancount.io/api-gateway/mcpClaude Code
ターミナルからサーバーを追加します:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpClaude Codeを開き、/mcpを実行してbeancountを選択し、その認証フローに従います。Beancount.ioにサインインし、要求された権限を確認します。/mcpに戻り、接続を確認します。クライアント固有の詳細については、Claude CodeのMCP手順を参照してください。
同意ページでは、アクセスを1つの元帳に制限するか、アクセス可能なすべての元帳を明示的に選択できます。単一元帳への制限は、良い出発点となります。より広いアクセスでは、alice/personalのように、使用する元帳をアシスタントに指示してください。元帳ツールは、各呼び出しでターゲットを識別する必要があります。
Claude DesktopおよびWeb上のClaude
Customize → Connectorsを開き、Add custom connectorを選択し、サーバーURLを入力して、Beancount.ioアカウントを接続します。使用したい会話でコネクタを有効にします。組織アカウントでは、先に所有者がコネクタを追加する必要がある場合があります。Claudeのリモートコネクタガイドに従ってください。
Cursor
個人用の~/.cursor/mcp.jsonにサーバーを追加します:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Cursorが要求したらOAuthサインインを完了し、サーバーのツールが利用可能であることを確認します。CursorのMCPドキュメントで、構成とツール承認設定について説明されています。
個人用APIキー
ベアラー資格情報を受け入れるクライアントの場合、設定 → 個人アクセストークンで個人用APIキーを作成できます。キーの作成には、有料のBeancount.ioプランが必要です。 クエリにはledger.readを選択し、必要に応じてキーを1つの元帳に制限し、表示されたらコピーします。クライアントの認証ヘッダーを、プライベートな資格情報設定を使用してAuthorization: Bearer YOUR_KEYとして構成します。
キーを共有プロジェクト構成に含めないでください。OAuthクライアントはサインインフローを通じて資格情報を管理します。そのパスでは個人キーを作成する必要はありません。
支出に関する質問から始める
接続後、元帳名を自分のものに置き換えてこれを試してください:
alice/personalを使用してください。その口座と通貨を特定し、2026年8月の支出を口座別に要約してください。各合計の背後にある日付範囲とBQLを示し、通貨は分けておき、元帳の検証エラーがあれば報告してください。何も変更しないでください。
アシスタントはlistLedgersで元帳を発見し、getLedgerContextで口座名を学習し、runBqlQueryStructuredで型付きクエリ結果を実行できます。checkLedgerは、検証エラー、エントリ数、最新のコミットを返します。
有用な回答には、元帳、期間、通貨、合計、およびそれを裏付けるクエリが含まれます。純資産に関する質問では、評価方法と使用された価格の日付も尋ねてください。取引の欠落や古い価格は、元帳が検証に合格しても回答を変える可能性があります。
プレビュー付きで取引を追加する
新しいエントリの場合、appendLedgerTextは通常のBeancountテキストを受け入れ、元帳の構成を使用してディレクティブをファイルにルーティングします。そのdry_runオプションは、コミット前に差分と予測される検証エラーを返します。
例:
2026年9月15日付けの4.50 USDのコーヒー購入を準備し、
Assets:Cashから支払い、Expenses:Foodに分類してください。それらの口座が存在するか確認し、まず一致する取引を探してください。appendLedgerTextをdry_run: trueで使用し、提案されたエントリとファイル差分を示し、私の確認を待ってください。
それらの口座がすでに開いている場合、提案されるエントリは次のようになります:
2026-09-15 * "Cafe" "Coffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USD自分の元帳の口座名を使用し、レビューを完了してください:
- プレビューで日付、金額、口座、宛先ファイルを確認します。
- アシスタントに適用してほしい正確な変更を確認します。
checkLedgerを実行し、結果のコミットとエラーを報告するように依頼します。
appendLedgerTextは、デフォルトで新しい検証エラーを拒否します。一般的なファイル変更にはeditLedgerFilesを使用します。これは、1つのGitコミットでファイルを作成、置換、更新、または削除できます。そのプレビューも差分と予測エラーを報告します。書き込み後に結果を確認し、checkLedgerを実行してください。成功したコミットにも会計エラーが含まれる可能性があります。
定期的な簿記にワークフローを使用する
サーバーは再利用可能なMCPプロンプトも提供します。プロンプトをサポートするクライアントは、コマンドまたはプロンプトピッカーでそれらを公開します:
| ワークフロー | 役立つこと |
|---|---|
spending-report | 裏付けとなるBQLを使用して支出に関する質問に答え、元帳への書き込みは行いません。 |
reconcile-account | 1つの口座を提供された明細書と比較し、差異を分類し、欠落しているエントリを提案します。 |
close-month | アクティブな口座、残高アサーション、定期取引、未解決フラグをレビューします。 |
categorize-imports | ステージングされた銀行取引をレビューし、既存の口座を使用してカテゴリを提案します。 |
これらのプロンプトは、アシスタントを手順に導きます。選択しただけで会計ジョブが実行されたり、追加の権限が付与されたりすることはありません。
照合には、明細書と期末残高が必要です。検証結果がクリーンなだけでは、すべての取引が記録されたことを確認できません。アシスタントに、検証できなかったものを特定し、それらの質問をレポートに残すように依頼してください。
銀行インポートの場合、最初にBeancount.ioで銀行をリンクしてください。接続詳細の読み取りには管理アクセスが必要です。ステージングされた取引の送信には、書き込み権限とその銀行接続への適切なアクセスが必要です。送信を承認する前に、提案されたカテゴリと重複を確認してください。
アクセスとデータ処理を理解する
接続の権限によって、アシスタントが実行できることが決まります:
| 権限 | アクセス |
|---|---|
ledger.read | 元帳データのクエリと読み取り。 |
ledger.write | データの読み取りと、通常の元帳変更。 |
ledger.admin | 許可された場所での読み取り、書き込み、および管理操作。 |
各元帳への既存のアクセスは引き続き適用されます。資格情報を1つの元帳に制限すると、元帳呼び出しが別の元帳をターゲットにできなくなります。制限のない資格情報は、アクセスできる元帳の中から選択できます。OAuthクライアントは要求する権限を選択するため、承認前に同意画面を読んでください。
MCPサーバーは、人間による承認ダイアログを表示しません。 クライアントの設定によって、ツールを呼び出す前にいつ尋ねるかが決まり、プレビューは明示的に要求する必要があります。提供される書き込みワークフローは、アシスタントに確認を待つように指示します。ledger.readに制限された資格情報は、書き込みなしで分析したい場合に強制された境界を提供します。
ツールの結果（クエリされた取引やアシスタントが読み取ったファイルを含む）は、AIクライアントのコンテキストに入り、そのモデルプロバイダーによって処理される可能性があります。Beancount.ioは、元帳、Git履歴、運用記録を保持します。ステートレスなMCP接続は、データが保持されないという約束ではありません。クライアントおよびプロバイダーのデータポリシーも適用されます。
失効した個人用APIキーは、後続のリクエストで拒否されます。OAuthアクセストークンは通常1時間有効です。リフレッシュトークンを失効させても、すでに発行されたアクセストークンはすぐには無効になりません。保護された操作が実行されるときに、元帳へのアクセスが再度チェックされます。
よくある質問
これでノートパソコンで元帳が開きますか？
ホストされたエンドポイントは、Beancount.ioの元帳で動作します。ローカルの.beanファイルを開くことはなく、Favaブラウザタブを開いておく必要もありません。
ダッシュボードのAIアシスタントとはどう違いますか？
ダッシュボードは独自のチャットインターフェースを提供します。MCPは、外部のAIクライアントから元帳機能を利用可能にし、そのクライアントの会話、モデル、承認設定を使用します。
ツールは見えるのに使えないのはなぜですか？
ツールカタログには、資格情報が許可しない操作が含まれています。エラーと付与された権限を確認してください。制限のない資格情報でも、元帳ツールには明示的な元帳ターゲットが必要です。
元帳を接続し、帳簿で検証できる1つの質問から始めてください。クエリを回答とともに保持し、元帳の維持に支援が必要になったら書き込み権限を追加してください。
