qbo-multicompany-mcp

qbo-multicompany-mcp

stdio 経由で、複数の QuickBooks Online 会社ファイルを 1 つの AI セッションに提供する、読み取り専用のMCP サーバーです。QuickBooks へのすべての呼び出しでは、明示的な entity キーで会社を指定します。既定の会社はなく、会社名による照合も行いません。

非公式です。Intuit とは提携しておらず、Intuit の承認も受けていません。各ユーザーが自分で Intuit アプリを登録し、Intuit からの質問に回答してください。

対象ユーザー

• 複数の QuickBooks 会社を運営、または帳簿を管理しており、会社を混同することなく、アシスタントにまたいで読み取らせたい方：月末締め、会社間の比較、取引の追跡、仕入先への支払いの照合などに利用できます。
• AI エージェント向けのツールを構築しており、モデルの実際の動作を踏まえて設計された MCP サーバーの実例を探している方。

QuickBooks の MCP サーバーはほかにもあり、Intuit 製のものや、複数の会社に対応したもの、帳簿への書き込みを行うものがあります。必要な機能と照らし合わせて比較してください。このサーバーは書き込みを一切行いません。

AI client  -- stdio -->  qbo-multicompany-mcp  -- GET, checked before send -->  QuickBooks Online
                              |
                              +-- entities.yaml        your companies, by key
                              +-- encrypted store      one token chain per company

サンドボックスでのクイックスタート

Python 3.11 以降、uv、および開発用リダイレクト URI として http://localhost:8765/callback を登録したIntuit 開発者アプリが必要です。

git clone https://github.com/dkaleganov/qbo-multicompany-mcp.git

cd qbo-multicompany-mcp && uv sync --frozen && cp entities.example.yaml entities.yaml && cp .env.example .env && chmod 600 .env entities.yaml

アプリの Client ID と Client Secret を .env に、サンドボックスの会社を entities.yaml に設定します。次に、ストアキーを作成して、ブラウザーで各会社に接続します。

uv run qbo-multicompany-mcp-auth --env-file .env --entities entities.yaml init-key

uv run qbo-multicompany-mcp-auth --env-file .env --entities entities.yaml connect acme_main

初回の接続では、通常、名前の不一致が報告されます。y と答え、表示された display_name を entities.yaml にコピーしてください。次に、絶対パスを使ってサーバーをクライアントに追加します。--scope user を指定すると、アカウント内のすべての Claude Code セッションで利用できるため、リポジトリフォルダーの外からもセッションを実行できます。

claude mcp add --scope user qbo -- "<repo>/.venv/bin/qbo-multicompany-mcp" --env-file "<repo>/.env" --entities "<repo>/entities.yaml"

docs/getting-started.mdでは、Claude Desktop と Codex を含むすべての手順を説明しています。本番環境では、さらに設定が必要です：docs/production.md。

クローンせずに PyPI から利用する

uvx を使うと、公開済みパッケージを実行できます。.env.exampleを .env として、entities.example.yamlを entities.yaml として、プライベートフォルダーに保存します。両方のファイルに chmod 600 を設定し、上記の手順で値を記入します。<dir> はそのフォルダーの絶対パスを表します。

uvx --from [email protected] qbo-multicompany-mcp-auth --env-file "<dir>/.env" --entities "<dir>/entities.yaml" init-key

uvx --from [email protected] qbo-multicompany-mcp-auth --env-file "<dir>/.env" --entities "<dir>/entities.yaml" connect acme_main

claude mcp add --scope user qbo -- uvx [email protected] --env-file "<dir>/.env" --entities "<dir>/entities.yaml"

ツール

デフォルトで18個、オプトインで1個です。docs/tools.mdには、すべてのパラメーターと「ツールの選び方」の表が記載されています。

ツール	戻り値
list_entities	設定済みの会社、認証状態、トークンの有効性。リクエストは行いません
server_info	ビルド、環境、読み取り専用の状態、ストアの保護状態。リクエストは行いません
get_company_info	会社のプロフィール、設定、そこから導出される機能
list_accounts	残高を含む勘定科目一覧
list_vendors	仕入先、1099 フラグ、納税者番号が登録されているかどうか。番号自体は返しません
list_customers	残高を含む顧客一覧。納税者番号、メモ、連絡先フィールドは含みません
list_reference_data	クラス、部門、品目、取引条件、支払方法、税コード、税率
list_transactions	最大6か月間の期間内の取引
get_transaction	明細行を含む単一の取引
run_query	解析ツリーから再構築され、GETで送信される、解析済みの単一のSELECT
list_changes	仕入先や勘定科目などのリストオブジェクトにおける、直近30日以内の変更と削除。取引は含みません
summarize_vendor_payments	暦年ごとの仕入先別候補合計額
report_profit_and_loss	区分ごとの収益と費用
report_balance_sheet	指定日時点の残高
report_general_ledger	勘定科目別の仕訳
report_aging	期間区分別の未決済買掛金または売掛金
run_report	ドキュメントに記載されたその他の21種類のレポート
list_attachments	添付ファイルのメタデータ。リンクは返しません
get_attachment（オプトイン）	--allow-documentsと固定されたストレージホストを指定した場合に限り、ファイルを返します

AI エージェントとうまく連携できる理由

モデルは間違った会社を呼び出し、空の結果を信頼し、誤った値を再試行することがあります。このサーバーは、その対策を中心に構築されています。

• すべての呼び出しで会社を明示します。 デフォルトがないため、モデルは毎回会社を指定する必要があり、誤った選択はトランスクリプトに表示されます。list_entities でキーを確認でき、各プロセスでの初回使用時にはガードが会社名を確認します。
• 結果には会社とデータの経過時間が示されます。 QuickBooks からのすべての回答には、エンティティ、環境、realm id（Intuit の Company ID）の末尾 4 桁、取得時刻が含まれるため、モデルは数値の出所となったファイルを明示できます。
• リストの語彙を統一しています。 QuickBooks のページをたどるすべてのリストは、count、rows、truncated、duplicates_dropped、pages_walked を返すため、モデルは一度で結果の形式を学習できます。
• 不完全なレポートは、まずその旨を示します。 セルや行に問題がある場合、結果は不完全となり、モデルが読むテキストは PARTIAL RESULT で始まります。空のレポートだけではデータがないとは判断できません。また、list_transactions は絞り込みリクエストで行が 0 件の場合、何もないと報告する前に、絞り込みなしで再確認します。
• 拒否時には修正方法を示し、値をそのまま返しません。 拒否時にはパラメーターとその理由を示し、通常はリクエストを送る前に応答します。送信したテキスト、ID、日付、数値は一切返しません。設定済みのエンティティキーや、このサーバー独自のオプション値を示すことはあります。テストでは、すべてのツールのすべてのパラメーターに識別用の値を送り、拒否メッセージにその値が繰り返し含まれないことを確認します。
• 会社のテキストには信頼できないデータであることを明記します。 名前、メモ、レポートのセルにはどんな内容も含まれ得ます。それらを返すすべてのツールの説明には、モデルにとって信頼できない入力であり、データがプロバイダーに送られる可能性があることを記載しています。
• サインインは人が行います。 同意はターミナルとブラウザーで行い、シークレットは環境から取得します。シークレットや認可コードを受け取るツールも、それらを返すツールもありません。あなたとして実行されているものは、どのフォルダーからでもプレーンテキストの .env とトークンストアのキーを読み取れます。AI セッションをリポジトリのフォルダー外に置くことで、.env と entities.yaml がエージェントの作業フォルダーに入るのを防げます。ただし、シェルを使えるエージェントは、SECURITY.md の説明どおり、両方のファイルとキーにアクセスできます。
• 説明で適切なツールへ案内します。 すべてのツールの説明には、別のツールのほうが適している状況が記載されています。また、docs/tools.md の「ツールの選び方」表では、ユーザー向けに機能全体を網羅しています。

読み取り専用と、その強制方法

Intuit には読み取り専用の会計スコープがありません。唯一のスコープで読み取りと書き込みの両方が可能です。そのため、読み取り専用はこのコードで実現しています。各リクエストは送信直前に、完全に構築された httpx.Request として検査されます。会計リクエストで許可されるのは、正確にバインドされた会社に対する、許可リストに含まれるパスへの GET のみです。OAuth 呼び出しは Intuit の固定エンドポイントに限られ、オプトインされた添付ファイルのダウンロードは指定したホストに限られます。それ以外はすべて拒否されます。docs/design.md では、ポリシーに加えて、ページ巡回、レポート、トークンストアの動作について説明しています。

検証方法

• テスト。 uv sync --frozen --extra dev を実行し、続けて uv run pytest -q を実行します。認証情報もネットワークアクセスも使わず、2,805 件が成功し、4 件がスキップされます。この件数には git 2.32 以降と、PATH 上に gitleaks が必要です。gitleaks がない場合は、さらに 25 件がスキップされます。
• ミューテーションゲート。 テストスイートの成功だけでは、安全動作が保護されているとは証明できません。そのため、scripts/mutation_gate.py には、各項目で一つの要素を削除し、テストが失敗することを求める480件のエントリーがあります。このゲート自体にも制御があるため、何もテストせずにひそかに通過することはありません。
• 漏えいチェック。 Intuit の認証情報を対象とするカスタム gitleaks ルールを用意し、それぞれカナリアで検出されることを確認しています。また、識別子の形式に一致する値には scripts/scrub_check.py を使用します。
• 実環境での実行。 すべてのツールをサンドボックスで stdio 経由で実行しました。今回のリリースのデフォルトツールと、プレリリースビルドの get_attachment が対象です。run_report 内の TaxSummary を除き、すべてのデフォルトツールを2026-09-28にプレリリースビルドで本番環境に対して読み取り専用で実行しました。TaxSummary は一度も行を返したことがありません。実環境での実行で判明したことは、docs/api-findings.md に記載されています。

CHANGELOG.md では、実環境で検証済みの内容と、フィクスチャでのみ実行した内容を分けて記載しています。

プロンプトの例

表示できる会社を教えてください。それぞれ接続されていますか？

acme_main と acme_ops の損益を、今年度の期初から現在までと前年度の同期間で比較してください。それぞれの数値の出典も示してください。

前四半期末時点の acme_ops の貸借対照表を表示し、その後、10%を超えて変動した勘定科目の仕訳を示してください。

acme_ops で1099フラグが設定されている仕入先はどれですか？

acme_main の2025年の仕入先支払い候補と、確認が必要な項目を教えてください。

既知の制限

• 読み取り専用で、QuickBooks Online のみ対応です。 書き込み機能はなく、QuickBooks Desktop にも対応していません。
• 取引には専用のツールがあります。 取引タイプに対して run_query は COUNT(*) に回答し、SELECT * は拒否します。list_changes も同様に拒否します。list_transactions と get_transaction を使用してください。
• フィルターの検証方法は異なります。 不明なパラメーター名は上流で破棄され、不正な列挙値は400になり、該当するものがない ID やテキストは空の200になります。このサーバーはそれぞれに対応しており、その方法については docs/design.md で説明しています。
• 仕入先支払い合計は候補値です。 銀行元帳との照合用であり、申告書の分類には使えません。また、銀行元帳と手作業で照合したことはありません。
• サンドボックスは本番環境ではありません。 サンドボックスで確認した値が、本番環境の会社でも有効とは限りません。
• 観測されていない列もあります。 クラス、部門、通貨のレポート列は文書化されていますが、実環境のレスポンスで確認されたことはありません。
• get_attachment はサンドボックスでのみ実証済みです。 本番環境のストレージホストは確認されておらず、ホストチェックは事前確認であり、接続先のアドレスを固定するものではありません。
• 一括取得はスナップショットではありません。 すべてのデータを取得できても、編集の前後にまたがる場合があります。結果には non_snapshot と表示されます。
• レート制限とクォータは Intuit の管理下にあります。 サーバーは文書化された両方の時間枠を適用し、カウントできない呼び出しは送信せず、制限に達した場合は待機せずに429を返します。
• uv.lock はリリース時点で固定されています。 サーバーとそのテストがインストールするすべてのパッケージが固定されているため、各自のスケジュールに合わせて uv lock --upgrade を実行してください。ビルドバックエンドの hatchling は含まれていません。uv はパッケージのビルド時にこれを解決します。

サポート

macOS でテスト済みです。Windows はサポート対象外です。ストアが POSIX ファイルロックに依存しているためです。Linux は QBO_TOKEN_KEY_SOURCE=env で動作するはずですが、テストされていません。本リリースで凍結されたアルファ版であり、可能な範囲で メンテナンスを行います。不具合の 報告を歓迎します。セキュリティに関する報告は SECURITY.md からお願いします。

ライセンス

MIT。LICENSE を参照してください。