quickbooks-mcp

QuickBooks MCP サーバー

QuickBooks Online 向けの MCP サーバーです。日々のワークフローで AI アシスタントを活用する簿記担当者、CFO、会計士向けに構築されています。

AI アシスタントに、損益計算書のレポートの取得、仕訳の作成、勘定科目残高の調査などを、API ペイロードではなく自然な言葉で依頼できます。

このサーバーを選ぶ理由

Intuit は、QuickBooks API を試す開発者にとって優れた出発点となる公式 MCP サーバーを提供しています。このサーバーは異なるアプローチを採用しており、本番環境の帳簿を扱う財務専門家向けに設計されています。

内部 ID ではなく自然な言葉を使えます

Intuit のサーバーでは、参照するすべての項目に QuickBooks の内部 ID が必要です。たとえば、請求書を作成する前に、仕入先の ID を調べる必要があります。このサーバーでは、名前を自動的に解決します。

"Create a bill for PG&E, $450 to Utilities, dated 2025-01-15"
→ Vendor, account, and department names are resolved automatically

財務レポートを標準搭載

レポート用ツールを備えた QuickBooks MCP サーバーは、これだけです。AI との会話を離れることなく、月、部門、クラス別に内訳を表示した損益計算書、貸借対照表、試算表を取得できます。

デフォルトで安全

すべての作成・編集操作は、デフォルトで下書き／プレビューモードになります。確定する前に、帳簿に書き込まれる内容を正確に確認できます。仕訳が誤って作成されたり、経費が誤分類されたりすることはありません。

複数のツールではなく、1つのクエリツール

エンティティの種類ごとに個別の検索ツールを用意する代わりに、単一の SQL 風 query ツールで、すべての QuickBooks エンティティを扱えます。AI アシスタントは SQL を自然に記述でき、QuickBooks がそれを検証するため、許可するフィールドのリストを管理する必要はありません。

"SELECT * FROM Purchase WHERE TxnDate >= '2025-01-01' AND TxnDate <= '2025-01-31'"

本番環境に対応した認証情報管理

個人利用の場合は認証情報をローカルに保存し、共有環境の場合は AWS Secrets Manager に保存できます。OAuth トークンは自動的に更新され、セッションをまたいで保持されます。

概要

	Intuit 公式	このサーバー
対象ユーザー	API を試す開発者	簿記担当者、CFO、会計士
名前の解決	QuickBooks の内部 ID が必要	名前を自動的に解決
財務レポート	なし	損益計算書、貸借対照表、試算表
書き込みの安全性	即時実行	デフォルトで下書きプレビュー
クエリ方式	エンティティごとの検索ツール	すべてのエンティティを対象にした SQL 風クエリ
認証情報	ローカルの .env ファイル	ローカルファイルまたは AWS Secrets Manager
配布方法	GitHub からクローン	npx quickbooks-mcp

前提条件

• QuickBooks 開発者アカウント：developer.intuit.comで登録してください
• Node.js 18+

インストール方法

用途に合ったセットアップ方法を選択してください。

セットアップ	おすすめの用途
NPM インストール	自分の QuickBooks アプリを使った手軽なセットアップ
ローカルチェックアウト	開発、カスタマイズ
AWS モード	共有環境／本番環境

---

オプション 1：NPM インストール

最も簡単に始められる方法です。認証情報はお使いのマシンにローカル保存されます。

1. QuickBooks アプリを作成する

1. developer.intuit.comにアクセスしてサインインします
2. 新しいアプリを作成します（または既存のアプリを選択します）
3. 「Keys & credentials」に移動します
4. Client ID と Client Secret を控えます
5. 「Redirect URIs」に、https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl を追加します

2. Claude Code に追加する

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"]
    }
  }
}

3. 認証情報を設定する

~/.quickbooks-mcp/credentials.json を作成します。

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

4. 認証する

Claude Code の起動後、qbo_authenticate ツールを使用します。

1. 引数なしで qbo_authenticate を呼び出して、認証 URL を取得します
2. ブラウザーで URL を開き、アプリを認証します
3. リダイレクト URL から code と realmId をコピーします
4. 認証コードと realm ID を指定して、もう一度 qbo_authenticate を呼び出します

OAuth トークンは保存され、自動的に更新されます。

---

オプション 2：ローカルチェックアウト

開発やカスタマイズ向けです。

1. QuickBooks アプリを作成する

上記のオプション 1 と同じ手順に従います。

2. クローンしてビルドする

git clone https://github.com/laf-rge/quickbooks-mcp.git
cd quickbooks-mcp
npm install
npm run build

3. Claude Code に追加する

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. 認証情報を設定する

クライアント認証情報を使って ~/.quickbooks-mcp/credentials.json を作成し（オプション 1 と同じです）、qbo_authenticate を実行して OAuth フローを完了します。

---

オプション 3：AWS モード

共有環境または本番環境向けです。認証情報は AWS Secrets Manager に保存されます。

1. AWS リソースを作成する

Secrets Manager にシークレットを作成します：

aws secretsmanager create-secret \
  --name prod/qbo \
  --secret-string '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "redirect_url": "https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl"
  }'

SSM Parameter Store に Company ID を保存します：

aws ssm put-parameter \
  --name /prod/qbo/company_id \
  --value "your_company_id" \
  --type SecureString

2. サーバーを設定する

quickbooks-mcp ディレクトリに .env ファイルを作成します。

QBO_CREDENTIAL_MODE=aws
AWS_REGION=us-east-2
QBO_SECRET_NAME=prod/qbo
QBO_COMPANY_ID_PARAM=/prod/qbo/company_id

注：Claude Code の既知のバグにより、.mcp.json の環境変数は MCP サーバーに確実に渡されません。回避策として .env ファイルが必要です。

3. Claude Code に追加する

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. IAM 権限

サーバーには、以下の AWS 権限が必要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:prod/qbo*"
    },
    {
      "Effect": "Allow",
      "Action": ["ssm:GetParameter"],
      "Resource": "arn:aws:ssm:*:*:parameter/prod/qbo/*"
    }
  ]
}

---

インライン出力モード

デフォルトでは、大きなレスポンス（レポート、クエリ結果）は /tmp ファイルに書き込まれ、サーバーはファイルパスを返します。この方法はターミナル環境の Claude Code では問題なく動作しますが、モデルが /tmp から読み取れない Claude Desktop や プラグイン環境 では機能しません。

すべてのレスポンスをインラインで返すには、QBO_INLINE_OUTPUT=true を設定します。

オプション A — .env ファイルで設定（ローカルチェックアウトで推奨）：

quickbooks-mcp ディレクトリに .env ファイルを作成します。

QBO_INLINE_OUTPUT=true

オプション B — .mcp.json の env ブロックで設定（NPM インストールで推奨）：

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CREDENTIAL_MODE": "local",
        "QBO_INLINE_OUTPUT": "true"
      }
    }
  }
}

注：Claude Code の既知のバグにより、一部の構成では .mcp.json の環境変数が MCP サーバーに確実に渡されません。オプション B が機能しない場合は、回避策として .env ファイルを使用してください。

---

環境変数

変数	デフォルト	説明
QBO_CREDENTIAL_MODE	local	認証情報の保存先：local または aws
QBO_CLIENT_ID	-	QuickBooks アプリの Client ID（ローカルモード）
QBO_CLIENT_SECRET	-	QuickBooks アプリの Client Secret（ローカルモード）
QBO_CREDENTIAL_FILE	~/.quickbooks-mcp/credentials.json	カスタム認証情報ファイルのパス。先頭の ~ はホームディレクトリに展開されるため、シェルによる展開が行われない MCP クライアントの JSON env ブロックでも使用できます。
QBO_INLINE_OUTPUT	false	/tmp ファイルに書き込まず、レスポンスをインラインで返します。ファイルベースの出力をモデルが利用できない Claude Desktop やプラグイン環境で必要です。
QBO_SANDBOX	false	QuickBooks のサンドボックス環境を使用します。また、「QuickBooks で表示」のディープリンクを app.sandbox.qbo.intuit.com に切り替え、本番環境の会社を開けないようにします。
AWS_REGION	us-east-2	AWS リージョン（AWS モード）
QBO_SECRET_NAME	prod/qbo	Secrets Manager のシークレット名（AWS モード）
QBO_COMPANY_ID_PARAM	/prod/qbo/company_id	SSM パラメータのパス（AWS モード）

---

利用可能なツール

ツール	説明
セットアップ
qbo_authenticate	OAuth 認証情報を設定します（ローカルモードのみ）
get_company_info	接続している会社の情報を取得します
クエリとレポート
query	QuickBooks の任意のエンティティに対して SQL 風のクエリを実行します
list_accounts	フィルターを適用して勘定科目一覧を取得します
get_profit_loss	損益レポート（月別、部門別、クラス別など）
get_balance_sheet	貸借対照表レポート
get_trial_balance	試算表レポート（flags: true を指定すると、貸借の逆側残高や未分類／仮勘定残高を確認する決算レビュー処理が追加されます）
get_report	その他 24 種類の QuickBooks レポート（売掛金と買掛金の経過期間別レポート、顧客と仕入先の残高、取引一覧、総勘定元帳、仕訳帳、顧客／商品／クラス／部門別売上、キャッシュフロー、および詳細版）
query_account_transactions	特定の勘定科目に影響するすべての取引（13 種類の転記エンティティ、ページネーション対応、任意でサブ勘定科目を集計。制限については docs/entity-coverage.md を参照）
account_period_summary	勘定科目の期間サマリー（期首残高／期末残高、借方、貸方、件数）
仕訳
create_journal_entry	仕訳を作成します（借方＝貸方であることを検証します。明細には entity_name／entity_type を指定します）
get_journal_entry	ID を指定して仕訳を取得します
edit_journal_entry	既存の仕訳を変更します
請求書
create_bill	仕入先請求書を作成します（明細には customer_name を指定します）
get_bill	ID を指定して請求書を取得します
edit_bill	既存の請求書を変更します
経費
create_expense	経費を作成します（現金、小切手、またはクレジットカード。支払先には仕入先、顧客、または従業員を指定できます）
get_expense	ID を指定して経費を取得します
edit_expense	既存の経費を変更します
売上レシート
create_sales_receipt	商品明細を含む売上レシートを作成します
get_sales_receipt	ID を指定して売上レシートを取得します
edit_sales_receipt	既存の売上レシートを変更します
請求書
create_invoice	商品明細を含む請求書を作成します（顧客の指定が必要です）
get_invoice	ID を指定して請求書を取得します
edit_invoice	既存の請求書を変更します
預入
create_deposit	銀行預入を作成します（明細には entity_name／entity_type を指定します）
get_deposit	ID を指定して預入を取得します
edit_deposit	既存の預入を変更します（明細には entity_name／entity_type を指定します）
仕入先クレジット
create_vendor_credit	仕入先クレジットを作成します（明細には customer_name を指定します）
get_vendor_credit	ID を指定して仕入先クレジットを取得します
edit_vendor_credit	既存の仕入先クレジットを変更します
請求書の支払い
create_bill_payment	請求書の支払いと仕入先クレジットの適用を行います（QBO の「小切手」／請求書支払いのフロー）
receive_payment	未決済の請求書に対する顧客の支払いを記録します（create_bill_payment に対応する売掛金側の処理）。各明細は請求書の未決済残高をデフォルト値として使用します
create_transfer	会社が保有する 2 つの勘定科目間で資金を移動します（銀行口座間、クレジットカードの返済）
get_bill_payment	ID を指定して請求書の支払いを取得します。未適用の金額をフラグで示します
仕入先
create_vendor	仕入先を作成します（連絡先、請求先住所、支払条件、口座番号、1099 フラグ）
edit_vendor	仕入先を部分更新します。active: false にすると無効になります。仕入先の読み取りには query を使用します
削除
delete_entity	任意の取引（仕訳、請求書、請求書、預入、売上レシート、経費、仕入先クレジット、請求書の支払い）を削除します

ベンダー、顧客、従業員の名前を指定する

明細行またはヘッダーに名前を割り当てられる書き込みツールはすべて、account_name や department_name と同様に、名前を受け取り、IDに解決します。どのパラメーターを使うかは、 QuickBooksに実際に保存される内容によって異なります。

パラメーター	適用される場所	受け付ける値
entity_name + entity_type	create_deposit / edit_deposit の明細行、create_journal_entry / edit_journal_entry の明細行、create_expense / edit_expense のヘッダーの支払先	ベンダー、顧客、または従業員。entity_type のデフォルトは Vendor です。
customer_name	create_bill / edit_bill、create_expense / edit_expense、create_vendor_credit / edit_vendor_credit の明細行	顧客のみ — QuickBooksはこれらの明細行に CustomerRef を保存し、ベンダーまたは従業員は指定できません。
vendor_name	create_bill、create_vendor_credit、create_bill_payment のヘッダー	ベンダーのみ。
customer_name（ヘッダー）	create_invoice、create_sales_receipt	顧客のみ。これらの明細行には行ごとのエンティティがありません。

いずれにも _id 形式（entity_id、customer_id）があり、内部IDがわかっている場合に使えます。編集ツールの明細行パラメーターには、次のルールが適用されます。

• パラメーターを省略すると、line_id で指定した明細行には、すでに設定されているエンティティが保持されます。
• 名前を指定すると、その値が設定または置換されます。
• 空の文字列（entity_name: ""）を渡すと、値がクリアされます。

各フィールドの形式は統一されていません。QBOのフィールド構造については、 docs/quickbooks-api-limitations.md を参照してください。

パラメーター名の検証

各ツールが公開するスキーマに照らして、引数は実行前に検証されます。不明なパラメーターを指定すると、最も近い有効なパラメーター名を示すエラーが発生します。必須パラメーターがない場合もエラーになり、変更するフィールドがない edit_* 呼び出しも、書き込みが成功したと報告する代わりにエラーになります。

その代わりに何も通知されないとしたらどうなるでしょうか。ハンドラーは認識しているパラメーターだけを読み取るため、スペルミスのあるパラメーターは単に存在しないものとして扱われます。日付を誤ったキーで指定した作成呼び出しでは今日の日付で登録され、日付範囲を指定した期間時点レポートでは今日の残高が返され、フィールド名をすべて誤って指定した編集では、何も変更されていないのに「正常に更新されました」と返されます。どの場合も、呼び出し元が気づけるエラーは発生しません。

関連事項として、QuickBooksがレコードの SyncToken を進めずに更新を受け付けた場合、つまり送信したデータがすでに保存されている内容と一致した場合、編集ツールは成功ではなく、変更なしと報告します。

---

トークンの更新

サーバーは各リクエストでOAuthトークンを自動的に更新し、認証情報ストア（ローカルファイルまたはAWS Secrets Manager）に保存し直します。

---

開発

npm run dev      # Run in development mode
npm run build    # Build
npm run typecheck # Type check
npm test         # Run the test suite

テストは tests/ にあり、src/ の構成を反映しています。テストはTypeScriptで記述され、tsconfig.test.json によって dist-test/ にコンパイルされ、Node組み込みのテストランナーで実行されます。テストフレームワークへの依存はありません。テスト内の型エラーはビルドエラーになるため、名前が変更されたエクスポートを参照するテストは、黙ってスキップされず明確に失敗します。QuickBooksクライアントが必要な処理には、テスト対象の呼び出しだけをカバーする手書きの代替実装を渡すため、認証情報がなくてもオフラインでテストスイートを実行できます。

---

トラブルシューティング

「QuickBooksの認証情報が設定されていません」

qbo_authenticate ツールを実行して、OAuth認証情報を設定してください（ローカルモードのみ）。

「認証コードの有効期限が切れています」

認証コードの有効期間は数分間です。OAuthフローをもう一度開始してください。

トークンの更新に失敗する

• リフレッシュトークンの有効期限が切れていないことを確認してください（約100日）。
• クライアント認証情報が正しいことを確認してください。
• qbo_authenticate で再認証してみてください。

AWS認証情報のエラー

• .env ファイルに QBO_CREDENTIAL_MODE=aws が設定されていることを確認してください。
• AWSの認証情報と権限を確認してください。
• シークレット名とパラメーター名が設定と一致していることを確認してください。