Claude CodeのIntuit DeveloperプラグインでQuickBooks連携アプリとサンドボックスを扱う
IntuitのDeveloperプラグインはMCPと2つのスキルで、QuickBooks連携のワークスペース・アプリ設定・OAuth・サンドボックスをClaude Codeから進めます。導入手順と、人が自分で行う場面を説明します。
Intuit Developerプラグインは、QuickBooksと連携するアプリを作る作業を、Claude Codeに手伝わせるためのプラグインです。Intuit Developer Platform上のワークスペースとアプリの設定、ブラウザでのOAuth、サンドボックス会社の管理、QuickBooks APIの呼び出しの組み立てまでを、MCPサーバーと2つのスキルで進めます。
導入は2コマンドで済みます。手間がかかるのは、その後の「人が自分の手で行う場面」です。クライアントシークレットの取得、本番キーの申請、ワークスペースの作成はプラグインからできません。この記事では、導入、作業の順序、サンドボックスの制約、つまずいたときの切り分けを順に説明します。
Intuit Developerプラグインが同梱するもの
プラグインはIntuitが運営するマーケットプレイス(intuit-marketplace)で配布されています。Claude CodeとCodexに対応し、ライセンスはApache-2.0です。中身は次の3つです。
- MCPサーバー: Intuit Developer Platformに接続するリモートのHTTPサーバーが1つ
- スキル:
connect-to-intuit-developer-platformとbuild-quickbooks-appの2つ - リファレンス: スキルが必要になった時点で読み進める手順書。常に全文を読み込むわけではない
2つのスキルの役割は、はっきり分かれています。
| スキル | 担当 |
|---|---|
connect-to-intuit-developer-platform | 担当初回接続のブラウザOAuth、開発者登録と利用規約の同意、アクセス権の復旧 |
build-quickbooks-app | 担当ワークスペース、アプリ、OAuth、サンドボックス、APIリクエスト、障害切り分けの一連の作業 |
接続が済んでいない状態で build-quickbooks-app が呼ばれた場合は、先に接続側のスキルへ回す作りです。
プラグインが送信するのは、ブラウザOAuthでサインインした後のセッション情報、ワークスペース・アプリ・サンドボックスの詳細、そして組み立てや検証を頼んだQuickBooks APIのリクエストです。ほかの宛先には送らないと、プラグインのREADMEに書かれています。サンドボックスの作成・リセット・削除は状態を変える操作で、頼んだときだけ実行されます。
Claude Codeへの導入手順
マーケットプレイスを追加してから、プラグインを入れます。
claude plugin marketplace add intuit/intuit-plugins-official
claude plugin install intuit-developer@intuit-marketplaceセッション内のスラッシュコマンドでも同じ操作ができます。
/plugin marketplace add intuit/intuit-plugins-official
/plugin install intuit-developer@intuit-marketplace入ったかどうかは claude plugin list で確かめます。一覧に intuit-developer@intuit-marketplace が有効として出れば成功です。読み込みには新しいセッションを開くか、/reload-plugins を実行します。更新は /plugin marketplace update intuit-marketplace です。
前提は3つあります。プラグインに対応したClaude Code(またはCodex)、Intuitアカウント、そしてOAuthのサインインを開くために同じマシンで使えるブラウザです。
2種類のOAuthを混ぜない
このプラグインには、名前の似た認証が2つ出てきます。混ぜると、原因の切り分けがつかなくなります。
プラグインに出てくる2つのOAuth
プラットフォームのセッション
Claude CodeがIntuit Developer Platformにつながるための認証です。MCPサーバーが401を返し、Claude Codeがブラウザのサインインを開き、受け取った資格情報を安全に保管します。開発者が値を触る場面はありません。
QuickBooksアプリのOAuth
開発者が作ったアプリが、QuickBooksの会社データにアクセスする許可を得るための認証です。アプリ自身のクライアントIDとシークレットを使い、トークンの交換と更新もアプリのコードが行います。
2つの資格情報、コールバック、スコープは別物として扱われます。トークン交換やトークン更新を行うMCPツールは存在しません。ツールを探したり、名前を想像して呼ぼうとしたりしないよう、スキルに明記されています。
初回接続の後は、Intuit_developer_connectivity_status を呼んで、成功してはじめて接続済みと判断する流れです。認証を避けるために静的なベアラートークンを足すことは、スキルの決まりでしません。
作業の順序は固定されている
build-quickbooks-app は、次の順で作業を進めます。順序は「見覚えのある値だから」という理由で飛ばさない決まりです。
build-quickbooks-appの進行順
- 1
プラットフォームへの接続
接続状態を確かめます。失敗したら接続側のスキルへ戻ります。
- 2
ワークスペース
所有するワークスペースを読み出します。複数あれば、名前と表示用IDを並べて選んでもらいます。
- 3
アプリと最小スコープ
既存アプリの再利用を先に勧め、新規作成は承認を得てから行います。
- 4
サンドボックス用の認証情報
クライアントIDを読み、シークレットは開発者が自分で取得します。
- 5
QuickBooksアプリのOAuth
アプリ側にコールバックを実装し、リダイレクトURIを登録します。
- 6
サンドボックスの準備確認
少なくとも1つのサンドボックスがあることを確かめます。
- 7
API検索と詳細取得
使う操作を検索し、必要なスコープとベースURLを取得します。
- 8
実リクエストと診断
実際に呼び出し、失敗したら原因を診断します。
進行中は、同じ進捗図を毎ステップ描き直して見せる決まりもあります。プロジェクトが空でなければ、先にフレームワークや既存のOAuth設定、環境変数名、リダイレクトURI、トークンの保存先を調べます。既存の実装がある場合は、2つ目のOAuth実装や別のアプリのディレクトリは作らず、今のルートや設定に合わせて最小の変更で組み込みます。
使うMCPツールは次の12個です。作成・更新・リセット・削除に当たるものは、実行前に対象と内容を示して明示的な承認を取ります。黙っているだけでは承認になりません。
| 区分 | ツール |
|---|---|
| 接続・ワークスペース | ツールIntuit_developer_connectivity_status / Intuit_developer_workspace_read |
| アプリ | ツールIntuit_developer_app_read / Intuit_developer_app_create / Intuit_developer_app_update |
| OAuthの接続先 | ツールIntuit_developer_oauth_details |
| サンドボックス | ツールIntuit_developer_sandbox_list / _create / _reset / _delete |
| QuickBooks API | ツールIntuit_quickbooks_api_search / Intuit_quickbooks_api_describe |
アプリ設定: スコープ、リダイレクトURI、シークレット
スコープは2種類から最小限を選ぶ
アプリを新規に作るとき、選べる実在のスコープは2つです。
com.intuit.quickbooks.accounting: 請求書、仕入請求書、顧客、仕入先、勘定科目の読み書きcom.intuit.quickbooks.payment: 支払い、チャージ、返金の作成と管理。サンドボックス会社は米国のものに限られる
少なくとも1つは必須で、「あとで決める」という選択肢はありません。決められないときは、何を作りたいのかを聞かれます。1つのワークスペースにMCP経由で作れるアプリは5つまでです。
後から権限が足りないと分かった場合は、Intuit_quickbooks_api_describe が返す必要スコープと、アプリの現在のスコープを突き合わせます。足りなければ「このスコープを追加してよいか」という単独の質問が来ます。追加は上書きではなく加算です。変更時に redirectUris などほかの項目と同じ更新に混ぜません。追加した後は、古いトークンに新しいスコープが入らないので、QuickBooksアプリのOAuthをやり直します。
リダイレクトURIは置き換えで登録される
リダイレクトURIの登録は、登録済みの一覧に新しい1件を足す操作に見えて、実際には一覧の置き換えです。そのため、アプリの詳細を読んで現在の redirectUrls を確認し、既存分と新規分の全体を送ります。更新後にはもう一度読み出して確かめます。
登録するURIは、次の3か所で一文字も違ってはいけません。
- アプリ設定に登録したコールバックURL
- 認可リクエストの
redirect_uri - トークン交換リクエストの
redirect_uri
スキルの例では http://localhost:9753/oauth/callback が使われますが、これは空のプロジェクト向けの例です。既存のプロジェクトでは、すでにあるコールバックのルートとポートを使います。
クライアントシークレットは人が取り出す
client_id は秘密ではないので、読み出して表示されます。client_secret はMCPが読み出しも返却もしません。代わりにアプリのKeysページへの portal_url が返るので、開発者がサインインして自分でコピーします。
落とし穴
シークレットをチャットに貼らない
スキルは .env を自分で作り、シークレット欄にはダミーの値を入れておきます。値を埋めるのは開発者が自分のエディタで行い、終わったらそう伝える流れです。チャットに貼る申し出があっても、受け取って書き込むことはしません。値を入れたら、アプリのプロセスを再起動してから試します。多くのランタイムは環境変数を起動時に一度だけ読むためです。
プロジェクトフォルダを選ばずに始めたセッションでは、.env のようなドットファイルがファイル一覧に出ないことがあります。この場合はエディタで開ける絶対パスを教えてもらうか、実際のプロジェクトフォルダへセッションを移します。
サンドボックスの扱いと制約
最初の実リクエストは、本番の会社ではなくサンドボックスに向けます。ここでは作業が2種類に分かれます。
アプリが顧客にOAuthでつなぐ通常の構成では、サンドボックスの一覧は「少なくとも1つあるか」の確認にしか使いません。どの会社を使うかは、アプリの /connect から開く本物のQuickBooks認可画面で開発者自身が選び、コールバックで返る realmId がそのつながりの対象になります。チャットで先にrealmを選ばせる必要はありません。
エージェントが直接1回だけ呼ぶ場合や、作成・リセット・削除のような破壊的な操作では、対象の確定が必要です。サンドボックスの一覧が返す realm_id を使い、推測した値や記憶した値は使いません。
サンドボックスの制約は次のとおりです。
| 項目 | 内容 |
|---|---|
| 上限 | 内容1ユーザーあたり10個。一覧に count / allowed / remaining が返る |
| リージョン | 内容US / CA / AU / IN / GB |
| SKU | 内容plus / advanced / ies_se / ies_me。plus 以外は米国のみ |
| 削除 | 内容作成から4時間は削除できない。削除は元に戻せず、IES Multi-Entityを消すと子会社も消える |
| リセット | 内容全テストデータが消える。10分に1回まで。対象は一覧の sandbox_id で指定する |
新しいサンドボックスを頼むと、まず既存のものの再利用が提案されます。それでも作る場合は、リージョンとSKUを別々の選択として確認し、作成そのものに対して別の承認を取ります。「もう1つ作って」という依頼だけでは、書き込みの承認になりません。上限に達していれば、再利用かリセットが案内されます。
実リクエストと、失敗したときの切り分け
APIを呼ぶ前には、Intuit_quickbooks_api_search で操作を探し、Intuit_quickbooks_api_describe で必要なスコープ、ベースURL、リクエストの形、cURLの例を取得します。ベースURLは取得した値をそのまま使います。OpenAPI定義の servers に書かれた一般的なホストを使うと、このプラットフォームのトークンが401になることがあります。エンドポイントやスコープを記憶で書かない、検索結果のサンプルを実データ扱いしない、というのがスキルの決まりです。
失敗したときは、同じリクエストをそのまま再送せずに診断します。
| ステータス | 見る順序・対処 |
|---|---|
| 401 | 見る順序・対処トークンの期限切れ(約1時間。アプリ側で更新)→ スコープ不足(追加後に再認可)→ 環境や会社とベースURL・realmの不一致 |
| 403 | 見る順序・対処権限の問題。再試行では直らないので、説明して止める |
| 400 | 見る順序・対処型、必須項目、minor version、realm ID、未解決のパスプレースホルダを、describeのスキーマと1項目ずつ照合 |
| トークンのエンドポイントが404 | 見る順序・対処認証情報ではなくパスの誤り。/oauth2/v1/tokens/bearer だけを使う |
結果が空だったときも、それらしい請求書や顧客を作って埋めることはありません。生のレスポンスを見て、日付の形式、タイムゾーン、1日ずれた範囲、厳しすぎる絞り込み、null許容のフィールドを確かめた後で、本当に空なのか取得に失敗したのかを判断します。デモ用のデータを頼んだ場合は、すべての表示にモックと明記されます。
プラットフォームの側でも決まったエラーが出ます。
- 開発者登録・利用規約: ほとんどのツールは、開発者プロファイルと利用規約への同意が必要です。未完了なら「サインインして利用規約に署名する」旨のメッセージが返るので、
developer.intuit.comで済ませてから同じ呼び出しを再試行します。同意を受け付けるMCPツールはありません AUTHORIZATION_ERROR: 障害ではなく権限の応答です。選んだワークスペースやアプリのIDを読み直し、サインイン中のアカウントを確かめます。ワークスペースが0件と返るのに所有しているはずの場合に限り、developer.intuit.comと別のアカウントで認証している可能性が残ります- 一部のツールだけ失敗: 接続状態の確認とワークスペースの読み出しは成功し、サンドボックスなど別の呼び出しだけが失敗するなら、認証済みだがセッションが古い状態の可能性があります。コネクタを再接続して同じ呼び出しを試し、同じ失敗が続くときにはじめて問い合わせます
No matching partner configuration: 再接続しても出るなら、AIプラットフォーム側のOAuthクライアント登録の問題です。動的クライアント登録(DCR)は使えず、登録はIntuitがAIプラットフォームごとに行います。開発者が静的トークンなどで回避することはできません
プラグインが扱えない範囲
次の操作は、プラグインにもMCPにも用意されていません。いずれも developer.intuit.com で行います。
- 本番キーの発行とアプリの昇格: 審査や検証は開発者ポータルで進めます。スキルは、本番用の認証情報や成功した本番呼び出しを、あるように見せません
- ワークスペースの作成: 所有するワークスペースが0件のときは、ポータルで作ってから
Intuit_developer_workspace_readに戻ります。所有できるワークスペースは合計10個です - ワークスペースとアプリの削除: ツールがなく、ポータルでもワークスペースは自分では消せません。再利用が勧められます
プラグインとMCPが対象にするのは開発環境で、本番での提供は検証できていないものとして扱われます。生成されたアプリは実行時にMCPを呼べないので、アプリのコードは、取得して検証したOAuthとAPIのエンドポイントを直接叩く形になります。
CLAUDE.mdに残しておくプロジェクトの規約
スキルが守る決まりの多くは、プロジェクト側の規約として書き出しておくと、別のセッションでも同じ動きになります。次のような断片が使えます。スキルの指示をプロジェクトの規約に言い換えた例です。
## QuickBooks連携
- クライアントシークレットは `.env` に置き、値の出力・コミット・チャット貼り付けをしない
- 既存のOAuthルートとリダイレクトURIを使い、2つ目の実装を作らない
- スコープは操作のdescribe結果にある最小限だけ。accountingを丸ごと要求しない
- 最初の実リクエストはサンドボックスに向ける。本番データは明示の指示があるときだけ
- APIの経路・スコープ・ベースURLは `Intuit_quickbooks_api_describe` の結果から取る
- 空の結果にダミーの請求書や顧客を足さない依頼は、目的と置き場所だけで足ります。たとえば次のように頼みます。
請求書の一覧を表示する画面を、このExpressアプリに追加したい。
Intuit Developerプラグインのスキルに沿って、既存のOAuthの
ルートを使い、サンドボックスの会社で動くところまで進めて。この依頼なら、まず接続の確認から入り、アプリの読み出し、スコープの突き合わせ、APIの検索と詳細取得の順で進みます。作成や更新の前には、対象とフィールドを示した確認が挟まります。承認の場面を「全部許可」で流してしまうと、このプラグインの安全装置は意味を失います。
まとめ
導入はマーケットプレイスの追加とプラグインのインストールの2コマンドで、作業の本体は固定された8段階の順序に沿って進みます。エージェントに任せられるのは、読み出し、承認つきの作成・更新、APIの組み立てと診断です。クライアントシークレットの取得、本番キー、ワークスペースの作成は人の仕事として残ります。
すでにアプリの実装があるプロジェクトでは、新規のスキャフォールドを頼まず、既存のOAuthルートに組み込む依頼にしたほうが、スキルの想定した動きに乗ります。Runway Devプラグインのように、ブラウザ認証とアプリ側の認証を分けて扱う型のプラグインに触れたことがあれば、考え方はほぼ同じです。比べるならClaude CodeにRunway Devプラグインを入れて動画生成APIをアプリに組み込むが参考になります。プラグインの配布や必須化についてはClaude Codeプラグインマーケットプレイスを必須化し、自動更新まで設定するも参照できます。未設定のオプションを後から埋めるときはclaude plugin configureでプラグインの未設定オプションを確認・保存するが使えます。