AI連携・MCP 利用ガイド

0. エージェントに渡す URL

次の URL を AI エージェント（Cursor・Antigravity・Claude・Codex・Grok など）のチャットに貼ると、 本ページの内容を読み取り、Zborra の使い方・ツール一覧・安全な手順を把握しやすくなります。

1. 誰向けか

• フリーランス・個人事業主で、AI に経理の下書きを手伝わせたい方
• Cursor / Claude / Codex / Antigravity / Grok など、ツール呼び出し型の AI を使っている方
• レシート撮影 → 仕訳 → 月次レビューを会話で進めたい方

2. 設計の原則（安全の考え方）

• AI が残高や税額を「それっぽく推測」して確定させない
• 書き込みは必ず内容確認のうえ実行する運用を前提にする
• エージェントは DB を直接触らない（Zborra 経由のみ）
• e-Tax 送信・税務判断の代行は行わない

3. 対応するエージェントの種類

接続の具体手順はエージェント製品ごとに異なります。多くの場合、MCP サーバ設定またはローカル連携を行います。Zborra デスクトップを起動し、ログインした状態で連携してください。

4. セットアップの流れ

1. Zborra デスクトップをインストールし、アカウントでログインする
2. 利用する AI エージェント側で「Zborra 連携 / MCP」を有効にする
3. エージェントが要求する認証情報（ログインセッションに紐づくもの）を、案内に従って設定する
4. 最初は読み取りだけ（勘定科目一覧・損益など）で疎通を確認する
5. 仕訳登録は、必ずプレビュー → 人の確認 → 確定の順で試す

証憑ファイルをパス指定で読ませる場合は、エージェントに許可するフォルダを必要最小限に限定してください（例: レシート専用フォルダのみ）。

設定例のイメージ（プレースホルダ）

実際のキー名・パスはインストール版・エージェント製品の最新案内に従ってください。以下は概念図です。

{
  "mcpServers": {
    "zborra-accounting": {
      "command": "（Zborra が案内する起動コマンド）",
      "env": {
        "ZBORRA_AGENT_API_TOKEN": "（ログイン後に取得するセッション用トークン）",
        "ZBORRA_AGENT_USER_ID": "（自分のユーザーID）"
      }
    }
  }
}

5. できる操作（ツール概要）

MCP では 22 ツールを公開しています。書き込み系は原則 confirm=true が必要です。

参照（読み取り）

• 勘定科目一覧
• 仕訳一覧（期間指定）
• 損益計算書・貸借対照表
• 青色申告用データ・納税概算・申告準備チェック
• 証憑一覧・未紐付け証憑の検出
• 経営指標スナップショット（P/L・B/S・ランウェイ・健全性・月次・経費上位・目標進捗を一括）
• 経営目標 JSON の取得・達成率

更新（書き込み・確認必須）

• 仕訳の登録・更新・削除
• 証憑のアップロード・仕訳への紐付け・解除
• 経費仕訳と証憑の一括登録
• 経営目標 JSON の保存（自由形式の目標定義）
• Ledger Loop（証憑→承認→確定→ローカル実仕訳）

MCP ツール一覧（名前）

ローカル REST（デスクトップ起動時・loopback のみ）でも同趣旨の API が使えます。例: GET /api/reports/management-indicators、GET|POST /api/goals、POST /api/loop/run、POST /api/loop/reconcile。

5.1 Ledger Loop（証憑→仕訳の閉ループ）

RunLedgerLoop（または POST /api/loop/run）は、証憑データの受け取りから承認・確定を経て、 ローカル帳簿に実仕訳を登録する一連の流れです。OCR はエージェント側、会計検証と仕訳保存は Zborra 側です。

• 成功時 localJournalId が実仕訳 ID（ListTransactions で確認可能）
• 応答不明時は ReconcileLedgerLoop で同じ冪等キーを再送（新キーを作らない）
• 仕訳作成に成功するまで Case を posted にしない（設計どおり）
• 書き込みには confirm=true が必要

# 推奨手順
1. ListAccounts で借方・貸方 ID を確定
2. レシート画像をエージェントが読む（ビジョン / OCR）
3. 利用者に仕訳案を提示して承認
4. RunLedgerLoop(confirm=true, base64 または filePath, …)
5. ListTransactions で登録を確認

6. 経営分析・指標データへのアクセス

仕訳・科目に加え、アプリが集計した経営指標を AI が読み取れます。 アプリ内にチャットを設けて「理由説明」まで行うのではなく、構造化された数値を AI に渡して追加分析する使い方を想定しています。

GetManagementIndicators で得られるもの（概要）

• 期間の損益（科目別）と貸借の要約
• 現金・預金残高とキャッシュ・ランウェイ（月数）
• 健全性チェック（固定費比率などの指標）
• 月次の収支推移、経費上位
• 設定済みの目標達成率

# エージェントへの依頼例
「今年の経営指標スナップショットを GetManagementIndicators で取って、
 ランウェイと売上・費用のポイントだけ短くまとめて」

「先月の損益と経費上位を出して。アプリ側の数字を使って」

7. 経営目標（JSON）の設定と達成率

個人事業・フリーランスでは「月次計画の固定フォーム」が合わないことが多いため、 目標は自由形式の JSONで定義します。AI に目標案を作らせて SetBusinessGoals で保存し、 デスクトップでは達成率・項目別進捗だけを見やすく表示します。

metric（集計の種類）

目標 JSON の例

{
  "name": "2026年目標",
  "goals": [
    {
      "key": "annual_revenue",
      "label": "年間売上",
      "target": 6000000,
      "metric": "revenue",
      "unit": "JPY",
      "periodStart": "2026-01-01",
      "periodEnd": "2026-12-31"
    },
    {
      "key": "july_expense_cap",
      "label": "7月経費上限",
      "target": 300000,
      "metric": "expense",
      "periodStart": "2026-07-01",
      "periodEnd": "2026-07-31"
    }
  ]
}

# エージェントへの依頼例
「年間売上 600 万、7月経費 30 万以内の目標 JSON を作って
 SetBusinessGoals で confirm=true で保存して」

「GetBusinessGoalProgress で今の達成率を見せて」

• 保存は confirm=true と書き込み権限が必要です
• 件数・文字数・metric はサーバ／アプリ側で検証されます（不正な HTML 等は除去）
• クラウド同期後、Web ダッシュボードでも目標の一覧（名称・目標値）を確認できます。仕訳から計算した達成率の詳細表示はデスクトップが本体です

8. 推奨ワークフロー

経費を文章で登録

1. 勘定科目一覧を取得
2. 仕訳案を作成し、内容を利用者に提示
3. 承認後に確定登録

レシート画像から登録（推奨）

1. エージェントが画像を読み取る（OCR / ビジョン）
2. ListAccounts で科目 ID を選ぶ
3. プレビューを人が確認
4. RunLedgerLoop(confirm=true) または RegisterExpenseFromReceipt(confirm=true)
5. ListTransactions で確認

月次レビュー

1. GetManagementIndicators または期間指定の損益
2. 仕訳一覧・未紐付け証憑の確認
3. 目標達成率（GetBusinessGoalProgress）
4. 必要ならデスクトップで月次 PDF を出力

確定申告の準備

1. 青色用レポート
2. 納税概算
3. 申告チェックリスト
4. 期末の貸借対照表

いずれも提出そのものは e-Tax / 税務署 / 税理士が行います。

9. デスクトップの月次 PDF・目標表示

AI 連携とは別に、アプリ本体でも次が使えます（個人事業主向けの「見る・出す」用途）。

• ダッシュボードの月次サマリー PDF … 年・月を選んで 1 枚の PDF を出力（売上・費用・利益・現金・ランウェイ・主な費用・目標進捗）
• 目標達成率ウィジェット … AI が設定した目標の進捗バー表示
• 分析期間の保持 … ダッシュボードで指定した期間は次回起動時も復元

10. 自動で検証される経理ルール（概要）

• 借方と貸方が異なること
• 金額が正であること
• 摘要があること
• 税率が妥当な範囲であること
• 適格請求書とする費用側では登録番号が必要な場合があること

日付は YYYY-MM-DD 形式で指定してください。

11. セキュリティと運用上の注意

• 連携は原則としてご自身の PC 上で完結させてください。インターネットに帳簿操作用の口を公開しないでください。
• 書き込みができるのは、権限のあるアカウントのみです。チーム利用時は権限を最小限に。
• エージェントに渡す画像・文章は必要最小限に（マイナンバーや無関係な通帳画像は送らない）。
• 「常に自動承認」「確認スキップ」の設定は使わないでください。目標の保存も confirm=true が必要です。
• 外部 AI サービスの利用規約・データの取扱いを確認してください。
• 開発・検証用の特別な緩和設定がある場合でも、本番の日常利用では有効にしないでください。
• 目標 JSON にはスクリプトや過剰に大きなデータを入れないでください（件数・サイズ制限があります）。

12. うまくいかないとき

関連リンク

• 解説記事：AIエージェントと経理
• アプリのダウンロード
• 操作マニュアル
• ヘルプセンター
• 利用規約（AI連携条項を含む）