QuickBooks Time MCP Server (Combined)

QuickBooks Time MCP サーバー（V2 アップデート）

これは、単一のインターフェースを通じて QuickBooks Time API のすべての機能にアクセスできる、統合型 MCP サーバーです。次の4つの個別サーバーの機能を統合しています。

1. ジョブコードツール
2. レポートおよびコアツール
3. タイムシートツール
4. ユーザーツール

このプロジェクトの改善にぜひご協力ください！ようやく何かをコミュニティに還元できてうれしいです！

このプロジェクト全体は、人工知能（Anthropic、OpenAI、Llama/META）を使って開発、公開しました。私自身は、支援なしでは多くのコードを書くことができないためです。品質と機能性を確保するためにあらゆる努力をしていますが、不完全な点や改善の余地がある場合があります。コミュニティからのフィードバック、修正、提案を歓迎します。

1. 依存関係をインストールします：

pip install -r requirements.txt

2. QuickBooks Time のアクセストークンを含む .env ファイルを作成します：

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude Desktop の設定

このサーバーを Claude Desktop で使用するには、Claude Desktop の設定で構成する必要があります。設定例を示します：

{
  "globalShortcut": "Ctrl+Q",
  "mcpServers": {
    "qb-time-tools": {
      "command": "python",
      "args": [
        "./qb-time-mcp-server/main.py"
      ],
      "env": {
        "QB_TIME_ACCESS_TOKEN": "your_quickbooks_time_access_token_here"
      }
    }
  }
}

利用可能なツール

ジョブコードツール

• get_jobcodes：高度なフィルタリングオプションを指定してジョブコードを取得します

  • 基本フィルター：
    • ids：（数値の配列、任意）ジョブコード ID のカンマ区切りリスト
    • name：（文字列、任意）ジョブコード名でフィルタリングします。文字列の先頭からワイルドカード（*）による一致に対応しています
    • active：（文字列、任意）ステータスでフィルタリングします："yes"、"no"、"both"（デフォルト："yes"）
  • 種類と階層のフィルター：
    • type：（文字列、任意）種類でフィルタリングします："regular"、"pto"、"paid_break"、"unpaid_break"、"all"（デフォルト："regular"）
    • parent_ids：（数値の配列、任意）親ジョブコード ID でフィルタリングします。特殊な値：0（最上位のみ）、-1（すべての階層）
  • 追加のフィルター：
    • customfields：（ブール値、任意）レスポンスにカスタムフィールドを含めます
    • modified_before：（文字列、任意）変更日でフィルタリングします（ISO 8601 形式）
    • modified_since：（文字列、任意）変更日でフィルタリングします（ISO 8601 形式）
    • page：（数値）ページネーションのページ番号
    • limit：（数値）ページあたりの結果数（最大200）

• get_jobcode：ID を指定して特定のジョブコードを取得します

  • 必須パラメーター：
    • id：（数値）取得するジョブコードの ID

• get_jobcode_hierarchy：ジョブコードの階層構造全体を取得します

  • パラメーター：
    • parent_ids：（数値の配列、任意）親 ID でフィルタリングします。値：0（最上位）、-1（すべて）、または特定の ID
    • active：（文字列、任意）ステータスでフィルタリングします："yes"、"no"、"both"（デフォルト："yes"）
    • type：（文字列、任意）種類でフィルタリングします："regular"、"pto"、"paid_break"、"unpaid_break"、"all"（デフォルト："regular"）
    • customfields：（ブール値、任意）レスポンスにカスタムフィールドを含めます

タイムシートツール

• get_timesheets：フィルター条件を指定してタイムシートを取得します

  • 必須パラメーター（少なくとも1つ）：
    • ids：（数値の配列）タイムシート ID のカンマ区切りリスト
    • start_date：（文字列）この日付以降のタイムシートを返します（YYYY-MM-DD）
    • modified_before：（文字列）この時刻より前に変更されたタイムシートを返します（ISO 8601）
    • modified_since：（文字列）この時刻以降に変更されたタイムシートを返します（ISO 8601）
  • 任意のパラメーター：
    • end_date：（文字列）この日付以前のタイムシートを返します（YYYY-MM-DD）
    • user_ids：（数値の配列）特定のユーザー ID でフィルターします
    • group_ids：（数値の配列）特定のグループ ID でフィルターします
    • jobcode_ids：（数値の配列）特定のジョブコード ID でフィルターします（子項目を含む）
    • payroll_ids：（数値の配列）特定の給与計算 ID でフィルターします
    • on_the_clock：（文字列）現在の勤務状況でフィルターします：「yes」、「no」、「both」（デフォルト：「no」）
    • jobcode_type：（文字列）種別でフィルターします：「regular」、「pto」、「paid_break」、「unpaid_break」、「all」（デフォルト：「all」）
    • page：（数値）ページ番号
    • limit：（数値）1ページあたりの結果数

• get_timesheet：ID を指定して特定のタイムシートを取得します

  • 必須パラメーター：
    • id：（数値）取得するタイムシートの ID

• get_current_timesheets：現在有効なタイムシートを取得します

  • 必須パラメーター：
    • on_the_clock：（文字列）「yes」に設定する必要があります
  • 任意のパラメーター：
    • user_ids：（数値の配列）特定のユーザーの有効なタイムシートでフィルターします
    • group_ids：（数値の配列）特定のグループに所属するユーザーの有効なタイムシートでフィルターします
    • jobcode_ids：（数値の配列）特定のジョブコードの有効なタイムシートでフィルターします
    • supplemental_data：（文字列）補足データを含めるか指定します：「yes」、「no」（デフォルト：「yes」）

ユーザーツール

• get_users：フィルターを指定してすべてのユーザーを取得します

  • ユーザー識別フィルター：
    • ids：（数値の配列、任意）指定したユーザー ID でフィルターします
    • not_ids：（数値の配列、任意）指定したユーザー ID を除外します
    • employee_numbers：（数値の配列、任意）従業員番号でフィルターします
    • usernames：（文字列の配列、任意）指定したユーザー名でフィルターします
  • グループフィルター：
    • group_ids：（数値の配列、任意）グループの所属情報でフィルターします
    • not_group_ids：（数値の配列、任意）指定したグループに属するユーザーを除外します
  • ステータスおよび識別フィルター：
    • payroll_ids：（文字列の配列、任意）給与識別番号でフィルターします
    • active：（文字列、任意）ステータスでフィルターします：「yes」、「no」、「both」（デフォルト：「yes」）
  • 名前フィルター：
    • first_name：（文字列、任意）名でフィルターします（ワイルドカード * に対応）
    • last_name：（文字列、任意）姓でフィルターします（ワイルドカード * に対応）
  • 時間ベースのフィルター：
    • modified_before：（文字列、任意）変更日でフィルターします（ISO 8601）
    • modified_since：（文字列、任意）変更日でフィルターします（ISO 8601）
  • ページネーション：
    • page：（数値、任意）ページ番号（デフォルト：1）
    • per_page：（数値、任意）1 ページあたりの結果数（デフォルト：50、最大：50）

• get_user：ID で特定のユーザーを取得します

  • 必須パラメーター：
    • id：（数値）取得するユーザーの ID

• get_current_user：現在認証されているユーザーを取得します

  • パラメーターは不要です
  • 次の情報を含む詳細なユーザー情報を返します：
    • 基本的なプロフィール情報
    • 会社の詳細情報
    • PTO 残高
    • 権限
    • カスタムフィールド

• get_groups：QuickBooks Time のすべてのグループを取得します

  • 任意のパラメーター：
    • ids：（数値の配列）指定したグループ ID でフィルターします
    • active：（文字列）ステータスでフィルターします：「yes」、「no」、「both」（デフォルト：「yes」）
    • manager_ids：（数値の配列）マネージャーのユーザー ID でグループをフィルターします
    • supplemental_data：（文字列）補足データを含めます：「yes」、「no」（デフォルト：「yes」）
  • 次の情報を含むグループ情報を返します：
    • グループの基本情報
    • マネージャーの割り当て
    • タイムシートの設定
    • 時間入力の設定
    • 休憩の設定

プロジェクト管理ツール

• get_projects：フィルターを指定してプロジェクトを取得します

  • 任意のパラメーター：
    • ids：（数値の配列）指定したプロジェクト ID でフィルターします
    • active：（文字列）ステータスでフィルターします：「yes」、「no」、「both」（デフォルト：「yes」）
    • client_id：（数値）クライアント ID でフィルターします
    • jobcode_id：（数値）関連付けられた jobcode ID でフィルターします
    • modified_before：（文字列）変更日でフィルターします（ISO 8601）
    • modified_since：（文字列）変更日でフィルターします（ISO 8601）
    • page：（数値）ページ番号（デフォルト：1）
    • per_page：（数値）1 ページあたりの結果数（デフォルト：50、最大：50）
  • 次の情報を含むプロジェクト情報を返します：
    • プロジェクトの基本情報
    • クライアントおよび jobcode との関連付け
    • 予算情報
    • 日付とステータス
    • カスタムフィールド

• get_project_activities：プロジェクトのアクティビティログを取得します

  • 任意のパラメーター：
    • project_ids：（数値の配列）特定のプロジェクトにアクティビティを絞り込みます
    • user_ids：（数値の配列）特定のユーザーでアクティビティをフィルターします
    • activity_types：（文字列の配列）アクティビティタイプでフィルターします：「status_change」、「note_added」、「budget_change」、「date_change」、「custom_field_change」
    • modified_before：（文字列）変更日でフィルターします（ISO 8601）
    • modified_since：（文字列）変更日でフィルターします（ISO 8601）
    • page：（数値）ページ番号（デフォルト：1）
    • per_page：（数値）1 ページあたりの結果数（デフォルト：50、最大：50）
  • 次の情報を含むアクティビティ情報を返します：
    • アクティビティのタイプと詳細
    • 変更を行ったユーザー
    • 変更前と変更後の値
    • タイムスタンプ

レポートツール

• get_current_totals：シフトおよび日次の合計を含む、現在の合計スナップショットを取得します

  • オプションのパラメーター：
    • user_ids：（数値の配列）特定のユーザーに合計を絞り込みます
    • group_ids：（数値の配列）特定のグループに属するユーザーの合計に絞り込みます
    • jobcode_ids：（数値の配列）特定のジョブコードに合計を絞り込みます
    • customfield_query：（文字列）次の形式でカスタムフィールドの値により絞り込みます：<customfield_id>||
  • 戻り値：
    • アクティブな時間エントリーのリアルタイムの合計
    • 所要時間と開始時刻
    • 関連するジョブコードとユーザーの情報
    • カスタムフィールドの値

• get_payroll：給与レポートを取得します

  • 必須パラメーター：
    • start_date：（文字列）給与期間の開始日（YYYY-MM-DD）
    • end_date：（文字列）給与期間の終了日（YYYY-MM-DD）
  • オプションのパラメーター：
    • user_ids：（数値の配列）特定のユーザーの給与に絞り込みます
    • group_ids：（数値の配列）特定のグループに属するユーザーの給与に絞り込みます
    • include_zero_time：（ブール値）時間エントリーがないユーザーを含めます（デフォルト：false）
  • 戻り値：
    • 種類別の合計時間（通常、時間外、倍額、PTO）
    • ユーザーごとの日別内訳
    • タイムシート数

• get_payroll_by_jobcode：ジョブコード別にグループ化した給与レポートを取得します

  • 必須パラメーター：
    • start_date：（文字列）給与期間の開始日（YYYY-MM-DD）
    • end_date：（文字列）給与期間の終了日（YYYY-MM-DD）
  • オプションのパラメーター：
    • user_ids：（数値の配列）特定のユーザーの給与に絞り込みます
    • group_ids：（数値の配列）特定のグループに属するユーザーの給与に絞り込みます
    • jobcode_ids：（数値の配列）特定のジョブコードの給与に絞り込みます
    • jobcode_type：（文字列）種類で絞り込みます："regular"、"pto"、"paid_break"、"unpaid_break"
    • include_zero_time：（ブール値）時間エントリーがないジョブコードを含めます（デフォルト：false）
  • 戻り値：
    • ジョブコード別の合計時間
    • 各ジョブコード内のユーザー別内訳
    • ジョブコードごとの日次合計

• get_project_report：時間エントリーを含む詳細なプロジェクトレポートを取得します

  • 必須パラメーター：
    • start_date：（文字列）YYYY-MM-DD 形式の開始日
    • end_date：（文字列）YYYY-MM-DD 形式の終了日
  • オプションのパラメーター：
    • user_ids：（数値の配列）特定のユーザーの時間エントリーに絞り込みます
    • group_ids：（数値の配列）特定のグループの時間エントリーに絞り込みます
    • jobcode_ids：（数値の配列）特定のジョブコードの時間エントリーに絞り込みます
    • jobcode_type：（文字列）種類で絞り込みます："regular"、"pto"、"unpaid_break"、"paid_break"、"all"（デフォルト："all"）
    • customfielditems：（オブジェクト）次の形式でカスタムフィールドの値により絞り込みます：{"customfield_id": ["value1", "value2"]}
  • 戻り値：
    • プロジェクトの合計時間
    • ユーザーおよびグループ別の内訳
    • 条件に基づいて絞り込まれた時間エントリー

追加ツール

• get_custom_fields：タイムカードに設定されたカスタム追跡フィールドを取得します

  • パラメーター：
    • ids：（数値の配列）特定のカスタムフィールド ID で絞り込みます
    • active：（文字列）ステータスで絞り込みます："yes"、"no"、"both"
    • applies_to：（文字列）適用先の種類で絞り込みます："timesheet"、"jobcode"、"user"
    • value_type：（文字列）値の種類で絞り込みます："managed-list"、"free-form"
    • page：（数値）ページ番号
    • limit：（数値）1 ページあたりの結果数

• get_last_modified：オブジェクトの最終更新日時を取得します

  • パラメーター：
    • types：（文字列の配列）確認するオブジェクトの種類（例：["timesheets", "jobcodes", "users"]）

• get_notifications：通知を取得します

  • パラメーター：
    • page：（数値）ページ番号
    • limit：（数値）1 ページあたりの結果数

• get_managed_clients：管理対象のクライアントを取得します

  • パラメーター：
    • page：（数値）ページ番号
    • limit：（数値）1 ページあたりの結果数

サーバーの実行

python main.py

サーバーが起動し、stdin/stdout で JSON-RPC リクエストを待ち受けます。

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。このプロジェクトは AI の支援を受けて開発されたため、コードベースの改善と保守において、コミュニティからの意見は特に貴重です。

サポート

問題や機能リクエストについては、GitHub のイシューのページをご利用いただくか、github.com/aallsbury から直接ご連絡ください。