QuickBooks Online

QuickBooks Online MCP サーバー

QuickBooks Online Accounting API向けの Model Context Protocol（MCP）サーバーです。QBO の 22 のエンティティにわたる 130 以上のツールと、10 種類の財務レポートを Claude およびその他の MCP 対応クライアントに提供します。

機能

• インタラクティブな請求書カード（MCP Apps、SEP-1865）：qbo_invoices_get は、MCP Apps ホスト（Claude Desktop/web）で読み取り専用のインタラクティブカードとして表示されます。顧客、ステータス、日付、明細項目、合計を表示します。デフォルトではニュートラルなデザインで、window.__BRAND__ の挿入または MCP_BRAND_* 環境変数を使ってブランド化できます。App 非対応のホストでは、同じ JSON ペイロード（_card フィールドを含む）が表示されます。

ワンクリックデプロイ

**レジストリ認証に関する注意：**このサーバーはパブリックな npm パッケージのみを依存関係としているため、Cloudflare と DigitalOcean のクラウドビルダーは認証なしで依存関係をインストールできます。ワンクリックデプロイにトークンは必要ありません。（今後のリリースでプライベートな @wyre-ai/* 依存関係が追加された場合は、ビルド変数として read:packages 権限を持つ GitHub PAT を指定します。Cloudflare Workers では NODE_AUTH_TOKEN、DigitalOcean ではビルド時の GITHUB_TOKEN シークレットを使用します。）

**公開済みパッケージのインストール：**リリース済みパッケージは GitHub Packages npm レジストリに公開されています。このレジストリでは、パブリックパッケージであっても、インストールのたびに認証が必要です。インストールするには、read:packages 権限を持つ GitHub PAT で npm を npm.pkg.github.com に認証してください。

export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/qbo-mcp

クイックスタート

前提条件

• Node.js >= 20
• QuickBooks Online OAuth2 アプリの認証情報（Intuit 開発者アカウントが必要です）

インストールとビルド

npm install
npm run build

実行（stdio モード）

QBO_ACCESS_TOKEN=your-access-token QBO_REALM_ID=your-realm-id npm start

実行（HTTP モード）

CONDUIT_S2S_SECRET が設定されるまで、HTTP の起動は拒否されます。リスナーのデフォルトは 127.0.0.1:8080 です。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  MCP_TRANSPORT=http \
  QBO_ACCESS_TOKEN=your-access-token \
  QBO_REALM_ID=your-realm-id \
  npm start

シークレットを指定しないローカル HTTP は、開発専用です。127.0.0.1 のみをバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST は無視され、上書きの試みはログに記録されます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 \
  QBO_ACCESS_TOKEN=your-access-token \
  QBO_REALM_ID=your-realm-id \
  npm start

Docker

コンテナ内でイメージは 0.0.0.0（MCP_HTTP_HOST）をリッスンし、AUTH_MODE=gateway がデフォルトです。ポートはループバックに公開し、実際の S2S シークレットを渡してください。ゲートウェイモードでは、アクセス トークンと realm ID はリクエストごとに X-Qbo-Access-Token と X-Qbo-Realm-Id として渡されます。環境変数からは読み込まれません。

# Generate the secret first: openssl rand -hex 32
docker build -t qbo-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  qbo-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE のデフォルトを gateway に設定します。QBO_ACCESS_TOKEN または QBO_REALM_ID は注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。そのうえで QBO_ACCESS_TOKEN と QBO_REALM_ID を使用します。

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e QBO_ACCESS_TOKEN=your-access-token \
  -e QBO_REALM_ID=your-realm-id \
  -p 127.0.0.1:8080:8080 \
  qbo-mcp

環境変数

変数	必須	デフォルト	説明
QBO_ACCESS_TOKEN	stdio および AUTH_MODE=env の場合	—	QuickBooks Online OAuth2 アクセストークンです。Compose ゲートウェイサービスではこの変数は読み込まれません。
QBO_REALM_ID	stdio および AUTH_MODE=env の場合	—	QuickBooks Online の会社（realm）IDです。Compose ゲートウェイサービスではこの変数は読み込まれません。
QBO_ENV	いいえ	production	API 環境です。production または sandbox を指定します。
QBO_CREDENTIALS_FILE	いいえ	—	リクエストごとに再読み込みされる dotenv 形式のファイルへのパスです。このファイル内の QBO_ACCESS_TOKEN／QBO_REALM_ID／QBO_ENV は環境変数より優先されます（トークンのローテーションを参照）。ゲートウェイの Compose サービスでは使用されません。
MCP_TRANSPORT	いいえ	stdio	トランスポートの種類です。stdio または http を指定します。
MCP_HTTP_PORT	いいえ	8080	HTTP サーバーのポートです。
MCP_HTTP_HOST	いいえ	127.0.0.1	MCP_TRANSPORT=http の場合のバインドアドレスです。CONDUIT_S2S_SECRET が設定されている場合、この値が適用されます。コンテナーイメージでは 0.0.0.0 が設定されます。シークレットが設定されていない場合、MCP_ALLOW_INSECURE_DEV=1 では 127.0.0.1 のみをバインドします。
AUTH_MODE	いいえ	env（イメージおよび Compose では gateway）	gateway または env です。ゲートウェイモードでは、各 /mcp リクエストに X-Qbo-Access-Token と X-Qbo-Realm-Id が必要で、QBO_* へのフォールバックは行いません。env モードでは、S2S 認証に成功した後にのみこれらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	—	サービス間シークレットです。openssl rand -hex 32 で生成します。この値が空、または既知のプレースホルダー（changeme、your-s2s-secret、secret、placeholder などの公開サンプル）の場合、HTTP サーバーはエラーをログに記録し、ゼロ以外の終了コードで終了します。Compose はこの値がないと起動しません。実際の値をコミットしないでください。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	—	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として正確に 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S を必須にせず、MCP_HTTP_HOST により広いアドレスが指定されていても、リスナーを 127.0.0.1 に強制的にバインドします。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_BRAND_NAME	いいえ	—	MCP Apps の請求書カードに表示するブランド名です（未設定の場合、カードは中立的な表示になります）。
MCP_BRAND_LOGO_URL	いいえ	—	請求書カードのロゴ URL です。
MCP_BRAND_PRIMARY_COLOR	いいえ	#2563eb	請求書カードのメインカラーです。
MCP_BRAND_ACCENT_COLOR	いいえ	#e5e7eb	請求書カードのアクセントカラーです。
MCP_BRAND_BG	いいえ	#ffffff	請求書カードの背景色です。
MCP_BRAND_TEXT	いいえ	#333333	請求書カードのテキスト色です。

認証

このサーバーは OAuth フローを処理せず、事前に取得されたアクセストークンを使用します。モードは 2 つあります。

env モード（プロセスのデフォルト）。 トークンは QBO_ACCESS_TOKEN から取得されます（または QBO_CREDENTIALS_FILE で指定したファイルから取得され、両方が設定されている場合はファイルが優先されます）。単一テナントです。Docker イメージおよび Compose ファイルでは、デフォルトでゲートウェイモードが使用されます。

ゲートウェイモード。 トークンはリクエストごとの HTTP ヘッダーから取得され、AsyncLocalStorage によって分離されるため、同時リクエスト間で認証情報が共有されることはありません。AUTH_MODE=gateway を設定し、X-Qbo-Access-Token と X-Qbo-Realm-Id を送信してください。どちらかのヘッダーがないリクエストには HTTP 401 が返され、プロセス環境内の QBO_ACCESS_TOKEN／QBO_REALM_ID へのフォールバックは行われません。

ヘッダー	必須	説明
X-Qbo-Access-Token	はい	OAuth2 アクセストークン
X-Qbo-Realm-Id	はい	会社（realm）ID
X-Qbo-Environment	いいえ	production または sandbox（デフォルトは production）

/health は認証不要のままで、認証情報を読み込みません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http と CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストには X-Gateway-S2S を含める必要があります。検証には src/s2s-verify.ts の verifyS2sHeader が使われます。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> に対して計算した HMAC-SHA256（小文字の 16 進数 64 文字）です。タイムスタンプはサーバーの時刻から 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報を読み取る前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Qbo-Access-Token: $QBO_ACCESS_TOKEN" \
  -H "X-Qbo-Realm-Id: $QBO_REALM_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway では、リクエストの認証情報ソースはこれらの X-Qbo-* ヘッダーのみです。AUTH_MODE=env では、ヘッダーがない場合、署名付きリクエストに環境変数の QBO_ACCESS_TOKEN と QBO_REALM_ID が使われます。

QBO がアクセストークンを拒否すると、サーバーはテキストがリテラルなプレフィックス QBO_UNAUTHORIZED: で始まる MCP エラーを返します。想定される仕様では、ゲートウェイがこのプレフィックスを検出して OAuth トークンを更新し、リクエストを再試行します。

トークンのローテーション（env モード）

QBO のアクセストークンは約 60 分で期限切れになるため、env モードのデプロイでは通常、cron ジョブを使ってローテーションします。Docker の env_file 内のトークンをローテーションしても、実行中のコンテナには反映されません。Docker が env_file を注入するのはコンテナの作成時だけです。そのため、docker restart では古い環境変数が維持され、呼び出しが QBO_UNAUTHORIZED / Token revoked で失敗し始めるまで、更新ループが何もせずに動作し続けます（#63）。

環境変数の再注入を完全に省くには、QBO_CREDENTIALS_FILE を設定します。サーバーはリクエストごとにファイルを読み直すため、ローテーションはすぐに反映され、再起動も再作成も不要です。

# Single-tenant HTTP. This is separate from the gateway Compose service,
# which does not set QBO_* credentials.
services:
  qbo-mcp:
    image: ghcr.io/wyre-ai/qbo-mcp
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      MCP_TRANSPORT: http
      AUTH_MODE: env
      MCP_HTTP_HOST: 0.0.0.0
      CONDUIT_S2S_SECRET: ${CONDUIT_S2S_SECRET:?set CONDUIT_S2S_SECRET}
      QBO_CREDENTIALS_FILE: /secrets/qbo.env
    volumes:
      - ./secrets:/secrets:ro   # mount the DIRECTORY, not the file

その後、更新ジョブは ./secrets/qbo.env（dotenv 形式：QBO_ACCESS_TOKEN=...、任意で QBO_REALM_ID=... と QBO_ENV=...）を書き換えるだけで完了です。スクリプトから docker restart を削除してください。ファイルそのものではなく、ファイルを含むディレクトリをマウントしてください。sed -i などのツールはファイルの inode を置き換えるため、単一ファイルのバインドマウントでは古いファイルを指したままになります。ファイルがない場合や読み取りできない場合、ツール呼び出しは古い環境変数のトークンに黙ってフォールバックせず、明確に失敗します。

通常の env_file による注入を使い続ける場合、ローテーションスクリプトでコンテナを再作成する必要があります。つまり、docker compose up -d --force-recreate を実行してください。docker restart だけでは不十分です。

サンドボックステスト

本番環境ではなく、Intuit のサンドボックス API（https://sandbox-quickbooks.api.intuit.com）を対象にするには、QBO_ENV=sandbox（env モード）または X-Qbo-Environment: sandbox（gateway モード）を設定します。認識されない値が指定された場合は、明確に失敗し、本番環境へ黙ってフォールバックすることはありません。

利用可能なツール

ツールはドメインごとに整理されています。ドメイン名（例：customers、vendors、bills）を指定して qbo_navigate を呼び出すと、そのドメインのツールを確認できます。ナビゲーションはツールを見つけるためのものであり、前提条件ではないため、すべてのツールを常に呼び出せます。

エンティティ（設定駆動、22種類のエンティティにわたる122個のツール）

各エンティティでは、list、get、create、update、void、searchの一部が利用できます。トランザクションエンティティでは、一覧操作でstartDate／endDateによる絞り込みが可能です。更新は差分のみを指定し、以前のgetで取得した現在のSyncTokenが必要です。voidはQBO Accounting APIが対応している場合にのみ公開されます（Invoiceでは?operation=void、Paymentでは?operation=update&include=voidを使用します）。Customerにはvoidや削除の機能がありません。無効化するには、update時にActiveをfalseに設定します。

販売ワークフロー

• qbo_customers_* — list、get、create、update、search（voidなし。Active: falseで無効化）
• qbo_invoices_* — list（Paid／Unpaid／Overdueのステータスで絞り込み）、get、create、update、void、send
• qbo_estimates_* — list、get、create、update
• qbo_sales_receipts_* — list、get、create、update
• qbo_credit_memos_* — list、get、create、update
• qbo_refund_receipts_* — list、get、create、update
• qbo_payments_* — list、get、create、update、void

購入ワークフロー

• qbo_vendors_* — list、get、create、update、search
• qbo_bills_* — list、get、create、update、search
• qbo_bill_payments_* — list、get、create、update
• qbo_vendor_credits_* — list、get、create、update
• qbo_purchases_* — list、get、create、update（POS経費）
• qbo_purchase_orders_* — list、get、create、update

銀行と資金移動

• qbo_deposits_* — list、get、create、update
• qbo_transfers_* — list、get、create、update
• qbo_journal_entries_* — list、get、create、update（借方／貸方の一致が必要）

商品と勘定科目

• qbo_items_* — list、get、create、update、search（商品とサービス）
• qbo_accounts_* — list、get、create、update、search（勘定科目表）

分類と支払条件

• qbo_classes_* — list、get、create、update、search
• qbo_departments_* — list、get、create、update、search
• qbo_terms_* — list、get、create、update、search（Net 30など）
• qbo_payment_methods_* — list、get、create、update、search

税金と会社情報

• qbo_tax_codes_* — list、get、search（読み取り専用）
• qbo_tax_rates_* — list、get、search（読み取り専用）
• qbo_company_info_* — list、get（読み取り専用の単一項目）

人員と時間

• qbo_employees_* — list、get、create、update、search
• qbo_time_activities_* — list、get、create、update（請求可能な時間）

添付ファイル

• qbo_attachables_* — list、get、create、update（メタデータのみ。ファイルのアップロードには別のQBOエンドポイントを使用します）

レポート（10個のツール）

• qbo_reports_profit_and_loss
• qbo_reports_balance_sheet
• qbo_reports_cash_flow
• qbo_reports_trial_balance
• qbo_reports_general_ledger
• qbo_reports_aged_receivables
• qbo_reports_aged_payables
• qbo_reports_customer_sales
• qbo_reports_customer_balance
• qbo_reports_vendor_expenses

レガシー経費ツール（後方互換性）

qbo_expenses_list_purchases、qbo_expenses_get_purchase、qbo_expenses_list_bills、qbo_expenses_get_billは引き続き利用できます。新しい作業では、create／update／searchが追加された専用のqbo_purchases_*およびqbo_bills_*ツールファミリーを使用してください。

テスト

npm test                   # unit suite — fast, no credentials needed
npm run test:integration   # hits a real QBO sandbox; skipped without creds

統合テストスイートは、IntuitのサンドボックスAPIに対して、各エンティティ層（顧客、仕入先、勘定科目、商品、仕訳、会社情報）につき読み取りツールを1つずつ呼び出します。環境にQBO_SANDBOX_ACCESS_TOKENとQBO_SANDBOX_REALM_IDの両方が存在する場合にのみ実行されます。CIでは、対応するリポジトリシークレットからこれらを設定し、シークレットがない場合は明確な通知を表示してジョブをスキップします。そのため、dependabotやフォークからのPRで失敗することはありません。

ライセンス

Apache-2.0