quickbooks-mcp-server

QuickBooks MCP サーバー

Claude Desktop と Claude Code を QuickBooks Online に接続し、自然言語で会計業務を行えます。請求書、経費、レポートなどについて、平易な英語で質問できます。

---

これは何ですか？

Claude が QuickBooks Online のデータに直接アクセスできるようにする MCP（Model Context Protocol） サーバーです。QuickBooks にログインしてレポートをクリックして確認する代わりに、Claude に尋ねるだけです。

「期限超過の請求書を金額順にすべて表示して」 「今四半期の損益はどうなっていますか？」 「Acme Corp 宛てに 2,500 ドルの請求書を作成して」

このサーバーが OAuth 認証、API 呼び出し、レート制限、データの書式設定を処理します。

---

クイックスタート

1. インストール

pip install quickbooks-mcp

または、ソースからインストールします。

git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e .

2. QuickBooks Developer App を作成する

1. developer.intuit.com にアクセスします
2. アプリを作成し、QuickBooks Online and Payments を選択します
3. Keys & OAuth で、Client ID と Client Secret を控えます
4. Redirect URI として http://localhost:8080/callback を追加します

3. 環境変数を設定する

export QBO_CLIENT_ID='your_client_id'
export QBO_CLIENT_SECRET='your_client_secret'

4. OAuth のセットアップを実行する

python scripts/setup_oauth.py

ブラウザーが開き、QuickBooks の認証が行われ、トークンがローカルに（暗号化して）保存されます。最後に表示される Realm ID を控えてください。

export QBO_REALM_ID='your_realm_id'

5. Claude Desktop を設定する

Claude Desktop の設定ファイル（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "quickbooks": {
      "command": "quickbooks-mcp",
      "env": {
        "QBO_CLIENT_ID": "your_client_id",
        "QBO_CLIENT_SECRET": "your_client_secret",
        "QBO_REALM_ID": "your_realm_id"
      }
    }
  }
}

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

6. 使用を開始する

Claude Desktop を再起動して、次のように試してみてください。

「現在の銀行口座残高を教えて」

---

全 19 種類のツール

無料プラン（9 種類のツール）

ツール	説明
list_invoices	ステータス、日付、顧客で請求書を一覧表示・絞り込み
get_invoice_details	明細項目と支払い履歴を含む請求書の詳細
get_overdue_invoices	支払期日からの経過日数順に並べた期限超過請求書
list_expenses	日付、取引先、金額、カテゴリで経費を一覧表示・絞り込み
get_top_expenses	任意の期間について、カテゴリまたは取引先別にまとめた上位の経費
get_account_balances	銀行口座、クレジットカード、またはすべての口座の現在残高
get_account_transactions	日付で絞り込める、任意の口座の最近の取引
search_customers	連絡先情報を含め、名前またはメールアドレスで顧客を検索
get_customer_summary	顧客の財務概要：請求額、支払額、未払い額

プレミアムプラン（10 種類のツール）-- 月額 $29

ツール	説明
get_profit_and_loss	任意の期間の損益レポート（収入・経費の内訳付き）
get_balance_sheet	任意の日付時点の貸借対照表（資産、負債、純資産）
get_cash_flow	キャッシュフロー計算書（営業、投資、財務）
get_accounts_receivable_aging	顧客別の売掛金の経過期間（未経過／30／60／90 日以上）
get_accounts_payable_aging	取引先別の買掛金の経過期間（未経過／30／60／90 日以上）
create_invoice	明細項目、支払期日、メモを指定して請求書を作成
record_payment	方法と参照情報を指定して請求書への支払いを記録
create_expense	取引先、金額、カテゴリ、日付を指定して経費を記録
get_financial_health	主要指標：流動比率、DSO、バーンレート、ランウェイ
compare_periods	期間を横並びで比較し、変化率を表示

プレミアムライセンスは nyxtools.dev/quickbooks-mcp で取得できます。

環境変数に設定します。

export LICENSE_KEY='your_license_key'

---

使用例

請求書

「1 月の請求書をすべて表示して」 「期限超過の請求書はどれですか？特に問題のあるものから表示して」 「請求書 #1042 の詳細を表示して」 「Acme Corp の未決済請求書を表示して」

経費

「今月はいくら使いましたか？」 「今四半期の経費カテゴリ上位10件を表示してください」 「今年、Amazonでいくら使いましたか？」

口座

「銀行口座の残高はいくらですか？」 「当座預金口座の直近20件の取引を表示してください」 「会社のクレジットカードの残高はいくらですか？」

顧客

「顧客のJohn Smithを検索してください」 「顧客456の財務概要を教えてください」 「未払い残高のある顧客を検索してください」

レポート（プレミアム）

「今四半期の損益計算書を表示してください」 「貸借対照表を表示してください」 「今月のキャッシュフローはどうですか？」 「売掛金のエイジングレポートを表示してください」 「支払いが最も遅い顧客は誰ですか？」

書き込み操作（プレミアム）

「顧客123の請求書を作成してください：ウェブサイトデザイン $2,500、ホスティング $150/月、支払期限は正味30日」 「請求書#1042に対する$1,000の小切手払いを記録してください」 「3月15日にクレジットカードで支払った、Office Depotでの備品購入費$250を記録してください」

分析（プレミアム）

「財務状況は健全ですか？主要な比率を表示してください」 「今月と先月を比較してください」 「今四半期を前年の同じ四半期と比較するとどうでしたか？」

---

設定

すべての設定は環境変数で行います。

変数	必須	デフォルト	説明
QBO_CLIENT_ID	はい		QuickBooks OAuth2 クライアント ID
QBO_CLIENT_SECRET	はい		QuickBooks OAuth2 クライアントシークレット
QBO_REALM_ID	はい		QuickBooks の会社／Realm ID
QBO_REDIRECT_URI	いいえ	http://localhost:8080/callback	OAuth リダイレクト URI
LICENSE_KEY	いいえ		プレミアムライセンスキー
QBO_SANDBOX	いいえ	false	サンドボックス環境を使用
TOKEN_STORE_PATH	いいえ	~/.quickbooks-mcp/tokens.json	トークンの保存場所
LOG_LEVEL	いいえ	INFO	ログレベル

---

セキュリティ

• 保存時のトークンは暗号化されます（マシン固有のキーを使用。Fernet + PBKDF2）
• トークンは自動更新されます――アクセストークンの有効期間は60分、リフレッシュトークンは100日です
• 認証情報はコードに保存されません――すべてのシークレットは環境変数で設定します
• QuickBooks API のレート制限に対応するため、レート制限機能が組み込まれています
• インジェクションを防ぐため、すべてのクエリパラメーターをサニタイズします

---

開発

# Clone and install with dev dependencies
git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=quickbooks_mcp

# Lint
ruff check src/ tests/

# Type check
mypy src/

プロジェクト構成

quickbooks-mcp-server/
  src/quickbooks_mcp/
    auth/          # OAuth2 flow and encrypted token storage
    client/        # QBO REST API client with rate limiting
    tools/         # MCP tool implementations (19 tools)
    utils/         # Money (Decimal), formatting, license validation
    server.py      # MCP server setup and tool registration
    config.py      # Environment-based configuration
  scripts/
    setup_oauth.py # Interactive OAuth setup
  examples/        # Config examples and usage guide
  tests/           # Pytest test suite

---

トラブルシューティング

「QuickBooks のトークンが見つかりません」

OAuth のセットアップを実行してください。

python scripts/setup_oauth.py

「トークンの更新に失敗しました」

リフレッシュトークンの有効期限が切れている可能性があります。OAuth のセットアップを再実行してください。

「QuickBooks API エラー（HTTP 403）」

アプリに com.intuit.quickbooks.accounting スコープがあることを確認してください。

「QuickBooks によってレート制限されました」

サーバーはレート制限を自動的に処理します。このエラーが表示された場合は、60秒お待ちください。

「これはプレミアム機能です」

一部のツールにはライセンスキーが必要です。こちらから入手するか、環境に LICENSE_KEY を設定してください。

サンドボックスモード

実際のデータに影響を与えずにテストするには：

export QBO_SANDBOX=true

Intuit の開発者ダッシュボードから開発用キー（本番用ではありません）を使用してください。

---

ライセンス

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

Copyright (c) 2026 NyxTools