QuickBooks Desktop MCP Server

QuickBooks Desktop MCP サーバー

Conductor API を通じて、Claude から QuickBooks Desktop の操作に直接アクセスできる、包括的な Model Context Protocol（MCP）サーバーです。このサーバーを使うと、財務管理、請求書処理、支払い処理、包括的なレポート作成について、QuickBooks と自然言語でやり取りできます。

🚀 機能

主な機能

• エンドユーザー管理：QuickBooks のエンドユーザーを作成・管理します
• 認証フロー：QuickBooks Desktop の認証セッションを処理します
• アカウント管理：勘定科目表の完全な CRUD 操作
• 請求書処理：明細項目を含む仕入先請求書を作成・更新・管理します
• 支払い処理：請求書に対する小切手およびクレジットカードでの支払いを処理します
• 財務レポート：概要を生成し、仕入先の支出パターンを分析します
• 高度な操作：API への直接アクセスと一括操作

技術的な機能

• マルチテナント対応：複数の QuickBooks 企業を処理します
• 堅牢なキャッシュ：応答の遅い Conductor API 呼び出しを最適化するローカルキャッシュシステム
• 包括的なエラー処理：再試行ロジックと詳細なエラーメッセージ
• 入力検証：すべての操作で Zod ベースのスキーマ検証を実行します
• 財務情報の表示形式：適切な通貨表示と金額処理
• ページネーション対応：大規模なデータセットをカーソルベースで移動できます

📋 前提条件

• Node.js 18 以降および npm
• Conductor と連携する QuickBooks Desktop
• Conductor API の認証情報（シークレットキー、公開可能キー）

🛠️ インストール

オプション 1：Claude Desktop との連携（推奨）

このサーバーを使う最も簡単な方法は、Git から直接インストールして Claude Desktop と連携することです。

1. リポジトリをクローンしてビルドする

   git clone https://github.com/alfork/qbconductor-mcp-server.git
   cd qbconductor-mcp-server
   npm install
   npm run build
   

2. Claude Desktop の設定に追加する

   Claude Desktop の設定ファイルを開き、次の内容を追加します。

   {
     "mcpServers": {
       "QuickBooks": {
         "command": "node",
         "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
         "env": {
           "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
           "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
           "CONDUCTOR_END_USER_ID": "end_usr_your_default_user",
           "CONDUCTOR_API_BASE_URL": "https://api.conductor.is/v1"
         }
       }
     }
   }
   

3. Claude Desktop を再起動する

   サーバーはローカルインストール先から読み込まれます。

オプション 2：ローカル開発環境のセットアップ

ローカル開発やカスタムデプロイの場合は、次の手順に従います。

1. リポジトリをクローンする

   git clone https://github.com/alfork/qbconductor-mcp-server.git
   cd qbconductor-mcp-server
   

2. 依存関係をインストールする

   npm install
   

3. 環境変数を設定する

   cp .env.example .env
   

   .env を編集し、Conductor API の認証情報を設定します。

   CONDUCTOR_SECRET_KEY=your_secret_key_here
   CONDUCTOR_API_KEY=your_publishable_key_here
   CONDUCTOR_END_USER_ID=your_default_end_user_id
   CONDUCTOR_API_BASE_URL=https://api.conductor.is/v1
   LOG_LEVEL=info
   CACHE_TTL_MINUTES=30
   CACHE_MAX_SIZE=1000
   

4. プロジェクトをビルドする

   npm run build
   

🔧 設定

Claude Desktop の設定（推奨）

このサーバーの設定には、Claude Desktop の設定ファイルを使用する方法を推奨します。ユーザー体験が最も優れており、すべての依存関係が自動的に処理されます。

必須の設定

Claude Desktop の claude_desktop_config.json に次の内容を追加します。

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user"
      }
    }
  }
}

オプションの設定

次のオプション環境変数を追加して、サーバーの動作をカスタマイズできます。

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user",
        "CONDUCTOR_API_BASE_URL": "https://api.conductor.is/v1",
        "LOG_LEVEL": "info",
        "CACHE_TTL_MINUTES": "30",
        "CACHE_MAX_SIZE": "1000",
        "DISABLED_TOOLS": "passthrough_request,bulk_operations"
      }
    }
  }
}

設定パラメーター

パラメーター	説明	必須	デフォルト
CONDUCTOR_SECRET_KEY	Conductor API のシークレットキー（sk_ で始まります）	はい	-
CONDUCTOR_API_KEY	Conductor API の公開可能キー（pk_ で始まります）	はい	-
CONDUCTOR_END_USER_ID	操作に使用するデフォルトのエンドユーザー ID（end_usr_ で始まります）	はい	-
CONDUCTOR_API_BASE_URL	Conductor API のベース URL	いいえ	https://api.conductor.is/v1
LOG_LEVEL	ログレベル（debug、info、warn、error）	いいえ	info
CACHE_TTL_MINUTES	キャッシュの有効期間（分）	いいえ	30
CACHE_MAX_SIZE	キャッシュする項目の最大数	いいえ	1000
DISABLED_TOOLS	無効にするツールのカンマ区切りリスト	いいえ	-

代替方法：環境変数

ローカル開発またはカスタム MCP クライアントとの統合では、環境変数を使用できます。

変数	説明	必須	デフォルト
CONDUCTOR_SECRET_KEY	Conductor API のシークレットキー	はい	-
CONDUCTOR_API_KEY	Conductor API の公開可能なキー	はい	-
CONDUCTOR_END_USER_ID	操作に使用するデフォルトのエンドユーザー ID	いいえ	-
CONDUCTOR_API_BASE_URL	Conductor API のベース URL	いいえ	https://api.conductor.is/v1
LOG_LEVEL	ログレベル（debug、info、warn、error）	いいえ	info
CACHE_TTL_MINUTES	キャッシュの有効期間（分）	いいえ	30
CACHE_MAX_SIZE	キャッシュする項目の最大数	いいえ	1000

カスタム MCP クライアントの設定

カスタム MCP クライアントでは、次の設定を使用してください。

{
  "mcpServers": {
    "qbconductor": {
      "command": "node",
      "args": ["/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "your_secret_key",
        "CONDUCTOR_API_KEY": "your_publishable_key",
        "CONDUCTOR_END_USER_ID": "your_end_user_id"
      }
    }
  }
}

🎯 利用可能なツール

エンドユーザー管理

• create_end_user - 新しい QuickBooks エンドユーザーを作成します
• list_end_users - すべてのエンドユーザーを一覧表示します
• get_end_user - 特定のエンドユーザーの詳細を取得します
• delete_end_user - エンドユーザーを削除します

認証

• create_auth_session - QuickBooks 認証 URL を生成します
• check_connection_status - エンドユーザーの接続状態を確認します

アカウント管理

• list_accounts - フィルタリング機能を使用して勘定科目一覧を取得します
• get_account - アカウントの詳細を取得します
• create_account - 新しい金融アカウントを作成します
• update_account - 既存のアカウントを変更します

請求書管理

• list_bills - 請求書を包括的なフィルタリング機能とともに取得します
• get_bill - 特定の請求書の詳細を取得します
• create_bill - 明細項目を含む新しい仕入先請求書を作成します
• update_bill - 既存の請求書を変更します

支払い処理

• list_bill_check_payments - 請求書に対する小切手払いを取得します
• list_bill_credit_card_payments - クレジットカード払いを取得します
• create_bill_check_payment - 小切手で請求書の支払いを処理します
• create_bill_credit_card_payment - クレジットカードで請求書の支払いを処理します
• update_payment - 既存の支払いを変更します
• delete_payment - 支払いを削除します

レポートと分析

• get_account_tax_lines - 税区分情報を取得します
• generate_financial_summary - アカウント全体の財務データを集計します
• get_vendor_spending_analysis - 仕入先別の支出を分析します

高度な操作

• passthrough_request - カスタム操作のための API 直接呼び出し
• bulk_operations - 複数のトランザクションを一括処理します

💡 使用例

基本的なアカウント操作

Claude: "Show me all expense accounts in QuickBooks"
→ Uses: list_accounts with accountType filter

Claude: "Create a new expense account called 'Marketing Software'"
→ Uses: create_account with proper account details

請求書管理

Claude: "Show me all unpaid bills from this month"
→ Uses: list_bills with date range and payment status filters

Claude: "Create a bill for $500 from Office Depot for office supplies"
→ Uses: create_bill with vendor and line item details

支払い処理

Claude: "Pay the Office Depot bill via check from our main checking account"
→ Uses: create_bill_check_payment with account and bill references

Claude: "Show me all payments made to vendors this quarter"
→ Uses: list_bill_check_payments and list_bill_credit_card_payments

財務分析

Claude: "Generate a financial summary for all expense accounts"
→ Uses: generate_financial_summary with account type filtering

Claude: "Analyze our spending by vendor for the last 6 months"
→ Uses: get_vendor_spending_analysis with date range

🏗️ アーキテクチャ

プロジェクト構成

src/
├── config.ts                 # Configuration management
├── logger.ts                 # Logging setup
├── index.ts                  # Server entry point
├── server.ts                 # MCP server implementation
├── services/
│   ├── conductor-client.ts   # Conductor API client
│   └── cache-service.ts      # Local caching service
├── schemas/
│   ├── conductor-types.ts    # Conductor API type definitions
│   └── mcp-schemas.ts        # MCP input validation schemas
├── utils/
│   ├── validation.ts         # Input validation utilities
│   ├── formatting.ts         # Response formatting utilities
│   └── error-handling.ts     # Error handling utilities
└── tools/
    ├── index.ts              # Tool registry
    ├── end-users.ts          # End-user management tools
    ├── auth.ts               # Authentication tools
    ├── accounts.ts           # Account management tools
    ├── bills.ts              # Bill management tools
    ├── payments.ts           # Payment processing tools
    ├── reporting.ts          # Reporting and analysis tools
    └── advanced.ts           # Advanced operation tools

主なコンポーネント

Conductor クライアント

• Conductor との REST API 直接統合
• 一時的な障害に対する自動リトライロジック
• 包括的なエラー処理とログ記録
• パフォーマンス最適化のための組み込みキャッシュ

キャッシュサービス

• API 呼び出しを減らすためのローカルキャッシュ
• 設定可能な TTL とサイズ上限
• パターンベースのキャッシュ無効化
• パフォーマンスの監視と統計

入力検証

• すべてのツールに対する Zod ベースのスキーマ検証
• 型安全なパラメーター処理
• 無効な入力に対する包括的なエラーメッセージ

応答のフォーマット

• すべてのツールで一貫した応答構造
• 通貨表示を含む金額のフォーマット
• メタデータの付与（タイムスタンプ、ID、リビジョン番号）
• 要約とページネーション情報を含むリストのフォーマット

🔒 セキュリティ

• API キー管理：環境変数を安全に処理します
• 入力のサニタイズ：すべての入力を包括的に検証します
• エラー処理：エラーメッセージから機密データを漏えいさせません
• マルチテナント分離：エンドユーザーのコンテキストを適切に管理します

🧪 テスト

テストスイートを実行します。

npm test

ビルドして検証します。

npm run build
npm run lint

📚 API リファレンス

ツール入力スキーマ

すべてのツールは、定義されたスキーマに従ってパラメーターを受け取ります。共通のパラメーターは次のとおりです。

• endUserId（任意）：マルチテナントのシナリオで、デフォルトのエンドユーザーを上書きします
• 日付フィルター：日付範囲には YYYY-MM-DD 形式を使用します
• ページネーション：大きな結果セットをカーソルベースで移動します
• フィルタリング：さまざまな QuickBooks のフィルターパターンをサポートします

レスポンス形式

すべてのツールは、次の形式でレスポンスを返します。

{
  "success": true,
  "data": { /* tool-specific data */ },
  "metadata": {
    "endUserId": "user_123",
    "timestamp": "2024-01-01T00:00:00Z",
    "totalCount": 10,
    /* additional metadata */
  }
}

エラーレスポンス：

{
  "success": false,
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "details": { /* additional error context */ }
  }
}

🚀 デプロイ

ローカル開発

npm run dev

本番ビルド

npm run build
npm start

Docker デプロイ

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]

📦 NPM への公開

公開するための前提条件

1. NPM アカウント：npmjs.comでアカウントを作成します
2. NPM CLI：npm がインストールされ、最新の状態であることを確認します
3. 認証：コマンドラインから NPM にログインします

公開手順

1. NPM にログイン

   npm login
   # Enter your NPM username, password, and email
   

2. パッケージ設定を確認

   # Check package.json is properly configured
   npm run build
   npm test
   

3. バージョン管理

   # For patch releases (bug fixes)
   npm version patch
   
   # For minor releases (new features)
   npm version minor
   
   # For major releases (breaking changes)
   npm version major
   

4. NPM に公開

   # Publish to public registry
   npm publish --access public
   
   # For scoped packages (recommended)
   npm publish --access public
   

5. 公開を確認

   # Check if package is available
   npm view @alfork/qbconductor-mcp-server
   
   # Test installation
   npx @alfork/qbconductor-mcp-server@latest --help
   

公開後

公開が正常に完了したら、NPM を使ったインストール方法に合わせてドキュメントを更新します。

{
  "mcpServers": {
    "QuickBooks": {
      "command": "npx",
      "args": ["-y", "@alfork/qbconductor-mcp-server@latest"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user"
      }
    }
  }
}

📖 ドキュメント

• セットアップガイド - 詳細なインストールおよび設定手順
• コントリビューションガイド - コントリビューター向けのガイドライン
• API リファレンス - 包括的な API ドキュメント
• 使用例 - 使用例と統合パターン
• トラブルシューティング - よくある問題と解決方法

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

詳細なガイドラインについては、CONTRIBUTING.mdを参照してください。

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🆘 サポート

サポートや質問については、次をご利用ください。

• このリポジトリで issue を作成する
• Conductor API ドキュメントを確認する
• MCP 仕様を確認する

🔗 関連プロジェクト

• Conductor API ドキュメント
• Model Context Protocol
• ClickUp MCP サーバー（参考実装）