QuickBooks Online MCP Server

QuickBooks Online MCP サーバー

Claude Desktop およびあらゆる MCP クライアント向けの QuickBooks Online MCP サーバーです。公式の MCP SDK（FastMCP）を使用して Python で実装されています。請求書、顧客、支払いに関する 18 個のツール（作成、読み取り、更新、削除、一覧表示、検索）に加え、会社情報と売掛金に関する読み取り専用リソースを提供します。実際の OAuth 2.1 認可コード + PKCE フロー、自動トークン更新、QuickBooks のスロットリングに準拠するクライアント側のレート制限、エージェントに次の操作を伝える構造化エラーを備えています。stdio および Streamable HTTP 経由で動作します。

関連項目：HubSpot CRM MCP Server · MCP Audit Gateway · What production MCP actually requires

アーキテクチャ

flowchart LR
    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
    subgraph Server["mcp-quickbooks (FastMCP)"]
        Tools["18 tools<br/>invoices · customers · payments"]
        Resources["resources<br/>company · receivables · customers"]
        Client["QBOClient<br/>retry · backoff · error mapping"]
        RL["RateLimiter<br/>per-second + per-minute buckets"]
        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
        Store[("token store<br/>.qbo_tokens.json")]
    end
    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]

    Agent <-->|stdio / streamable-http| Tools
    Agent <-->|resources/read| Resources
    Tools --> Client
    Resources --> Client
    Client --> RL
    Client --> Auth
    Auth <--> Store
    Auth <-->|token + refresh| QBO
    Client -->|REST + query| QBO

サーバーは状態を保持せず、顧客データも保存しません。QuickBooks REST API のステートレスなプロキシとして動作します。トークンはユーザーが管理するローカルファイルに保存され、クライアントは独自の Intuit 認証情報を使ってデプロイします。

ツール

各ツールは、構造化された { "ok": true, ... } の結果、または suggestion を含む { "ok": false, "error": {...} } を返します。いずれのツールにも MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）と、宣言された出力スキーマがあります。

• create_customer：顧客を作成します。表示名は一意である必要があります。重複すると QuickBooks はエラー 6240 を返します。
• get_customer：Id を指定して顧客を 1 件読み取り、残高、連絡先情報、現在の SyncToken を取得します。
• update_customer：既存の顧客を部分更新します。Id と最新の SyncToken が必要です。
• delete_customer：顧客を無効化します（QuickBooks では顧客を完全削除できません）。履歴は保持されます。
• list_customers：顧客を最終更新日時の新しい順に一覧表示します。ページネーションは呼び出し側で指定します。
• search_customers：表示名の前方一致、メールアドレスの完全一致、または有効フラグで顧客を検索します。
• create_invoice：既存の顧客に対して、1 つ以上の明細項目を含む請求書を作成します。
• get_invoice：Id を指定して請求書を 1 件読み取り、明細、合計、残高、現在の SyncToken を取得します。
• update_invoice：請求書を置き換えます。明細はすべて置き換えられるため、更新後に残す明細をすべて送信してください。
• delete_invoice：請求書を完全に削除します。Id と最新の SyncToken が必要です。
• list_invoices：請求書を取引日が新しい順に一覧表示します。ページネーションは呼び出し側で指定します。
• search_invoices：顧客 Id、取引日の範囲、または伝票番号で請求書を検索します。
• create_payment：受け取った支払いを記録します。必要に応じて特定の請求書に適用できます。
• get_payment：Id を指定して支払いを 1 件読み取り、関連する取引と現在の SyncToken を取得します。
• update_payment：支払いを置き換えます。請求書との関連付けを解除すると、その請求書の残高が再び未払いになります。
• delete_payment：支払いを完全に削除します。支払いによって決済済みになった請求書は、未払いに戻ります。
• list_payments：支払いを取引日が新しい順に一覧表示します。ページネーションは呼び出し側で指定します。
• search_payments：顧客 Id または取引日の範囲で支払いを検索します。

リソース

読み取り専用の JSON：

• qbo://company：会社概要と登記上の住所
• qbo://summary/receivables：未決済／延滞請求書の件数と未収残高
• qbo://summary/customers：未収残高の多い順に並べた有効な顧客

最小権限のスコープ

デフォルトのスコープは com.intuit.quickbooks.accounting のみです。決済処理に接続する場合に限り、QBO_SCOPES を介して com.intuit.quickbooks.payment を追加してください。スコープ文字列は起動時に既知の Intuit スコープセットと照合して検証されるため、誤記があれば権限不足のまま処理が続くのではなく、すぐにエラーになります。ID スコープ（openid、profile、email）は、明示的に有効にしない限り要求されません。

レート制限と再試行

二重トークンバケット方式のリミッターにより、QuickBooks の秒単位と分単位の両方の上限に合わせて送信トラフィックを制限します（QBO_REQUESTS_PER_SECOND / QBO_REQUESTS_PER_MINUTE で設定可能です）。429 の場合、クライアントは Retry-After ヘッダーに従います。ヘッダーがない 429 / 5xx の場合は、QBO_MAX_RETRIES まで、ジッターを加えた指数バックオフを使用します。401 が発生すると、トークンを更新して透過的に一度だけ再試行します。

クイックスタート

uv venv --python 3.12 .venv
uv pip install -e ".[dev]"

cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
mcp-quickbooks status      # verify the token refreshes

mcp-quickbooks stdio       # run over stdio (Claude Desktop)
mcp-quickbooks http --port 8000   # run over Streamable HTTP

認証情報は必要になった時点で読み込まれます。サーバーは起動し、initialize に応答し、QBO_* 変数が一切設定されていなくても tools/list を提供します。認証情報なしでツールを呼び出すと、呼び出し元に設定方法を伝える構造化された 401 が返されます。これにより、シークレットなしでレジストリのイントロスペクションとコンテナーのスモークテストを実行できます。

Claude Desktop

{
  "mcpServers": {
    "quickbooks": {
      "command": "mcp-quickbooks",
      "args": ["stdio"],
      "env": { "QBO_ENVIRONMENT": "sandbox" }
    }
  }
}

Docker

docker build -t mcp-quickbooks .
docker run --rm -i --env-file .env mcp-quickbooks

実際の Intuit サンドボックスに接続して実行する

1. Intuit Developer portal でアプリを作成し、Keys & OAuth セクションを開きます。Development のクライアント ID とシークレットをコピーします。
2. .env の QBO_REDIRECT_URI に一致するリダイレクト URI を追加します（デフォルトは http://localhost:8765/callback です）。
3. 開発者ダッシュボードでサンドボックス企業を作成します。その企業 ID が QBO_REALM_ID です。
4. QBO_ENVIRONMENT=sandbox を設定し、QBO_CLIENT_ID / QBO_CLIENT_SECRET を入力してから、mcp-quickbooks auth を実行します。ブラウザ認証フローで realmId が自動的に返され、トークンとともに保存されます。
5. mcp-quickbooks status でトークンが更新されることを確認します。これで実際のサンドボックスを操作できます。

実際の帳簿に接続するには、本番用キーと接続済み企業を用意したうえで、QBO_ENVIRONMENT=production に切り替えます。認証情報とトークンはご自身で管理するものであり、リポジトリにコミットされることはありません。.env と .qbo_tokens.json は gitignore の対象です。

テスト

テストスイートは完全にオフラインで実行されます。すべての QuickBooks および OAuth 呼び出しは、httpx のモックトランスポートを介して組み込まれた、記録データ形式のフィクスチャ（tests/fixtures/）をシードとして使うメモリー内のフェイク（tests/fake_qbo.py）によって処理されます。ネットワーク接続も実際の認証情報も必要ありません。

uv run pytest

レジストリのメタデータ

server.json は MCP レジストリ向けにサーバーを記述し、.mcp.json はディレクトリクローラーが検索するクライアント設定スニペットです。公開は意図的に手動の手順として残しています。 詳しくは PUBLISHING.md を参照してください。ここからレジストリに何かが送信されることはありません。

お仕事のご依頼

AI 時代の重要な資金関連インテグレーションを、本番環境で安全に運用できるようにします。実際の認証、実際のレート制限、実際のエラー処理、実際のテストに対応します。MCP サーバーの構築と API インテグレーションの堅牢化を承ります。ポートフォリオと連絡先：https://amin-ale.github.io/portfolio-site · [email protected]

ライセンス

MIT：詳細は LICENSE を参照してください。