housecall-pro-mcp

Housecall Pro MCP サーバー

Housecall Pro API 用のオープンソース MCP サーバーです。Claude、ChatGPT、Cursor など、MCP 対応の AI エージェントを Housecall Pro アカウントに接続すれば、レポートをクリックして回る代わりに、必要な情報を尋ねられます。

独立したプロジェクトであり、Housecall Pro とは提携、推奨、スポンサー関係にありません。私たち自身が Housecall Pro を利用するサービス会社を運営しており、そのためにこのプロジェクトが生まれました。

インストール

Node 18 以降と Housecall Pro API キーが必要です。API アクセスは MAX プランに含まれており、それより下位のプランでは利用できません。

Claude Desktop。 Settings、Developer、Edit Config の順に開き、次を追加します。

{
  "mcpServers": {
    "housecall-pro": {
      "command": "npx",
      "args": ["-y", "housecall-pro-mcp"],
      "env": { "HCP_API_KEY": "your-api-key-here" }
    }
  }
}

Claude Desktop を再起動すると、Housecall Pro ツールが表示されます。

Claude Code。 直接追加します。

claude mcp add housecall-pro -e HCP_API_KEY=your-api-key-here -- npx -y housecall-pro-mcp

または、プラグインとしてインストールできます。キーの入力が求められます（キーはキーチェーンに保存され、設定ファイルには保存されません）。読み取り専用とツールセットの切り替えを、インストール時のオプションとして設定できます。

/plugin marketplace add hcpapi/housecall-pro-mcp
/plugin install housecall-pro@hcpapi

Cursor、Codex、その他の MCP クライアント。 stdio 経由で MCP を利用するクライアントであれば、どれでも動作します。コマンドに npx、引数に ["-y", "housecall-pro-mcp"] を指定し、環境変数に HCP_API_KEY を設定してください。

キーの取得には約 1 分かかります。手順はHousecall Pro API キーの取得に記載されています。

Housecall Pro API の癖と、このサーバーによる対処

これらは Housecall Pro API 自体の注意点です。それぞれ、ドキュメントだけをもとにインテグレーションを構築すると、エラーではなく誤った結果を返す箇所です。

API の動作	このサーバーの対処
金額は整数のセント単位です。そのため、$250 は 25000 です。	双方向に変換します。$250 は常に $250 として扱われ、$2.50 になることはありません。
フラットなスケジュールキー、説明、タグを送ると、PATCH /jobs は200 を返しますが、何も変更しません。	API が受け付けるネストされたスケジュールオブジェクトだけを送信するため、成功の報告は実際の成功を意味します。
ジョブの説明は明細項目から生成されるため、直接設定できません。	何もせずに終わる説明フィールドではなく、明細項目の書き込み機能を提供します。
請求書のフィルターに使えるのは created_at、due_at、paid_at、amount_due で、service_date や invoice_date では絞り込めません。未対応のフィルター名は拒否されず、受け入れられたうえで無視されます。	エンドポイントが実際に受け付ける名前を使い、サーバー側に同等の機能がないサービス日の期間指定は、クライアント側でページをたどって処理します。
work_status は、たとえば completed ではなく complete unrated のように、書き込み時と異なる表現で返されます。	読み取り時に正規化するため、ステータスフィルターは結果がゼロになるのではなく、実際のレコードに一致します。
削除済みのジョブも一覧レスポンスに表示され、合計件数にも含まれます。	すべての行で deleted_at を示して警告するため、収益が過大に計上されることはありません。
ジョブからタグを削除すると、そのタグが実際に付いていたかどうかにかかわらず、空の成功レスポンスが返ります。	削除を確認できない場合に削除したと断言せず、リクエストが受け付けられたことを報告します。
アーカイブ済みのジョブは、予約の説明を返しません。	ジョブがアーカイブ済みであることを示して空のリストを返すため、全件の処理が途中で止まりません。
請求書のドキュメントは非常に長い HTML ページであり、PDF ではありません。	ページの先頭部分と、それが全体のどの程度に当たるかを返します。
添付ファイル専用のルートはありません。ジョブの添付ファイルのパスに対する GET は HTML の 404 を返しますが、expand[]=attachments を指定すると署名付きダウンロードリンクとともに取得できます。	expand を指定してファイルを返します。リンクはリクエストごとに発行されるため、要求された時点で取得され、保存されることはありません。
PUT でしか応答しないルートがあり、同じパスに対する POST は HTML の 404 ページを返します。これは誤ったメソッドではなく「そのようなルートはない」と読み取れる内容です。	各ルートが実際に受け付けるメソッドを使うため、クルーの割り当てや明細項目の一括更新が、存在しないように見えることなく機能します。

Housecall Pro への書き込みで 2xx が返っても、決して信用しないでください。 レコードを読み戻して確認してください。複数のルートは、何も変更していなくても 200 を返します。そのため、上記の行が設けられています。

hcp コマンドライン

同じパッケージで hcp もインストールされ、ターミナルから同じ Housecall Pro の機能を利用できます。コードは同一です。各コマンドは以下のツールのいずれかに対応し、同じ変換、同じフィルター、同じ拒否動作を行います。

MCP サーバーはアシスタントが起動している間だけ動作するため、このコマンドラインが用意されています。毎週月曜の朝に売掛金の経過レポートを書き出すスケジュールタスクは、MCP クライアントでは実行できません。

npm install -g housecall-pro-mcp     # or run it once with: npx -p housecall-pro-mcp hcp
export HCP_API_KEY=your-api-key-here

hcp list jobs --work-status completed --page-size 20
hcp jobs list --page-size 20                    # the same command, read either way round
hcp get customer cus_1a2b3c
hcp search customers "smith"
hcp list invoices --csv > unpaid.csv

Node 18+ が動作する環境であれば、Windows、macOS、Linux で利用できます。

出力。 デフォルトでは、ターミナルの幅に合わせた表が出力されます。すべてのレコードを出力するには --json、スプレッドシートやスケジュールされたエクスポートには --csv を指定します。データは標準出力に、補足情報は標準エラー出力に送られるため、リダイレクトすればデータだけを取得できます。

変更する前に。 --dry-run を指定すると、コマンドが送信する内容を正確に表示し、何も送信しません。--read-only を指定すると、アカウントを変更する可能性のあるコマンドを拒否し、拒否の原因となったスイッチを表示します。

コマンドの確認方法。 hcp を単独で実行すると、グループ別にコマンドが一覧表示されます。hcp commands はコマンドを1行ずつ表示し、hcp commands --json は書き込みを行うコマンドも含めた一覧全体を表示します。hcp <command> --describe はコマンドを実行せずに、そのパラメーターを表示します。

hcp create customer --first-name Alex --last-name Rivera --dry-run
hcp list jobs --describe

以下のスイッチのうち、サーバーに適用されるものはすべてこちらにも適用されます。--toolsets もその一つです。

ドキュメントに記載されているが、存在しないルート

Housecall Pro の公開ドキュメントには、以下のルートが記載されています。しかし、これらは存在しません。ドキュメントだけを基に統合を構築すると、それぞれについて機能しないコードパスが実装されます。

ドキュメント上の記載	実際の仕様
POST、PUT、DELETE /appointments	存在しません。予約はジョブの下にネストされたものだけです。
PUT /jobs/{id}	存在しません。PATCH /jobs で反映されるのは、ネストされたスケジュールオブジェクトのみです。
POST /invoices	存在しません。
DELETE /customers/{id}	存在しません。公開されている顧客削除機能はありません。
PUT または DELETE /customers/{id}/addresses/{adr}	存在しません。住所は追記のみ可能です。
PUT または DELETE /estimates/{id} および /estimates/{id}/options/{opt}	存在しません。
PUT または DELETE /leads/{id}	書き込みルートとしては存在しません。リードを更新または削除することはできません。読み取りは可能です。GET /leads、GET /leads/{id}、GET /leads/{id}/line_items はすべて利用できます。
DELETE /tags/{id}	存在しません。API 経由でタグを削除することはできません。
DELETE /jobs/{id}/tags	存在しません。
PUT /jobs/{id}/lock	ルートではなく、HTTP メソッドが存在しません。POST /jobs/{id}/lock で1件のジョブをロックできます。一括処理用の POST /jobs/lock も存在し、ジョブ ID のリストではなく starting_at をキーとして使います。
POST /api/price_book/services	存在しません。資材とカテゴリは通常どおり作成できます。
GET /webhooks/subscription	存在しません。
GET /employees/{id}	存在しません。従業員の詳細ルートはありません。GET /employees が返した ID を使っても HTML の 404 が返されます。一覧から該当する行を読み取ってください。

できること

• 「6月の請求額をサービス別に集計して」
• 「今週予定されているジョブのうち、未払い残高があるものを一覧表示して」
• 「Elm Street に住む Smith 家の顧客レコードを開いて」
• 「『Service Plan』タグが付いている顧客は？」
• 「第2四半期の請求書を CSV でエクスポートして」
• 「給湯器に関する価格表の内容は？」
• 「job_123 の予約日時と、担当者を教えて」
• 「顧客に表示される内容で invoice_123 を見せて」
• 「顧客を新規登録して：John Baker、22 Elm St, Springfield IL、+1 555 123 4567」
• 「cus_123 向けに、給湯器の交換を2,400ドル／3,100ドル／3,900ドルとした松竹梅の見積もりを作成して」
• 「job_123 に火曜日の午前8時から10時で Mike を予約して」
• 「その訪問を木曜の午前中に変更して、代わりに Dave を担当にして」
• 「Mike と Dave を job_123 に派遣して」
• 「job_123 のすべての作業項目の価格を一度に再設定して」
• 「顧客がその見積もりの中間の選択肢を選んだので、承認済みにして」
• 「営業時間と、来週の空き状況を教えて」
• 「ジョブの所要時間をデフォルトで90分にし、到着時間に2時間の幅を設けて」

Housecall Pro API キーの取得

1. Housecall Pro に管理者としてサインインします。オフィススタッフのログインではキーを生成できません。
2. 上部バーにあるグリッドアイコンの My Apps を開きます。
3. Go to App store をクリックし、API を検索して API Key Management を開きます。カタログ全体ではなく一部だけがメニューに表示されるため、通常は My Apps メニューに表示されていません。
4. Generate new API key をクリックし、名前を付けてアクセスレベルを選択します。
   • 読み取り専用。レポート作成、検索、エクスポートに使用します。アカウント全体での書き込みは拒否されますが、実際に確認した例外が1つあります。/api/price_book/ 配下の価格表ルートはこの制限の対象外であり、読み取り専用キーでも価格表カテゴリを作成および削除できます。ほぼ確実ではなく、確実に書き込みを防ぎたい場合は、このサーバーを --read-only 付きで実行してください。この場合、書き込みツール自体が登録されません。
   • フルアクセス。顧客、案件、見積もりの作成も可能になります。
5. キーをコピーします。Housecall Pro ではその後もこのページにキーが表示されるため、戻って再度コピーできます。キーは編集できません。アクセスレベルを変更するには、新しいキーを生成して古いキーを削除する必要があります。

スクリーンショット付きの手順は https://hcpapi.com/mcp/#key にあります。

選択したアクセスレベルが実際の制限になります。このサーバーは生成したキーの設定に従うため、読み取り専用キーでは書き込みツールにアクセスできません。質問に答えるだけのアシスタントが必要な場合は、読み取り専用キーを生成してください。Housecall Pro がその制限を適用します。

キーを生成できるのは管理者のみであり、管理者はアカウント全体にアクセスできるため、このキーは特定のユーザーの範囲ではなく、アカウント全体にアクセスできます。

ツール

96 個のツールがあります。読み取りにはどのキーでも使用できますが、書き込みにはフルアクセスキーが必要です。ツールはツールセットごとにまとめられているため、インストール時に必要なグループのみを登録できます。詳しくは登録するツールの選択を参照してください。

読み取り

ツール	内容
hcp_get_company	会社のプロフィール。アカウントのタイムゾーンとデフォルトの到着時間帯を含みます
hcp_get_schedule_availability	アカウントの営業時間と、どれだけ先まで予約を受け付けるかを取得します
hcp_list_booking_windows	Housecall Pro が予約可能として報告する時間帯と、そのうち空いている時間帯を取得します
hcp_search_customers	顧客を検索または一覧表示するか、タグで絞り込みます
hcp_get_customer	1 人の顧客の全レコードを取得します
hcp_contactability	顧客への連絡が安全かどうかを確認します。API が読み取れる「連絡不可」のシグナルをすべて統合し、読み取れないシグナルも明示します
hcp_list_jobs	ステータス、スケジュール期間、または顧客で案件を取得します
hcp_get_job	1 件の案件の全レコードを取得します
hcp_get_job_notes · hcp_get_job_count	案件のメモと、アカウントの案件総数を取得します
hcp_list_job_appointments	案件の予約済み訪問、時間帯、技術者を取得します
hcp_get_job_line_items	1 件の案件の明細項目をドル建ての価格で取得します
hcp_get_job_input_materials	請求対象とは区別して、案件で実際に使用された資材を取得します
hcp_list_checklists	案件または見積もりに添付されたチェックリストを取得します
hcp_list_invoices	日付範囲内の請求書を取得します。ステータス（paid、open、canceled）で絞り込めます
hcp_get_invoice	1 件の請求書の全情報を、支払い、返金、残高とともに取得します
hcp_get_job_invoices	全リストをたどらずに、1 件の案件の請求書を取得します
hcp_get_invoice_document	顧客に表示される請求書ページのプレビューを取得します
hcp_list_estimates	オプション、承認日、割り当てられた従業員を含む見積もりを取得します
hcp_get_estimate	1 件の見積もりの全情報を取得します
hcp_get_estimate_line_items	見積もりオプションの明細項目を取得します
hcp_list_leads · hcp_get_lead	未成約の問い合わせと、明細項目を含む 1 件のリードを取得します
hcp_list_events · hcp_get_event	反復設定と参加者を含む、案件以外のカレンダー項目を取得します
hcp_get_customer_address	顧客ではなく ID がある場合に、ID で住所を 1 件取得します
hcp_get_application	アカウントに登録されている API アプリケーションがあれば取得します
hcp_list_routes	指定日のルートを取得します。従業員ごとに、割り当てられた作業をまとめて表示します
hcp_list_service_zones	郵便番号と出張料金を含むサービスエリア、および郵便番号が対象エリア内かどうかを取得します
hcp_list_pipeline_statuses	案件、リード、または見積もりに設定されたワークフローのステージを取得します
hcp_search_pricebook	サービス、資材、カテゴリ、価格フォームを検索します
hcp_list_price_forms	所要時間と予約時の質問を含む、予約可能なサービスのテンプレートを取得します
hcp_list_employees	従業員と役割を取得します
hcp_list_tags · hcp_list_job_types · hcp_list_lead_sources	アカウントの参照情報を取得します
hcp_revenue_summary	月別または明細項目別の請求済み収益を取得します
hcp_render_report	調査結果を、並べ替え可能なテーブル、選択可能な行、印刷機能を備えたインタラクティブなレポートにまとめます。対応クライアントでは会話内に表示され、それ以外では自己完結型の HTML ファイルとして返されます。API 呼び出しは行いません
hcp_export_csv	顧客、案件、請求書、または見積もりを CSV 形式でエクスポートします
hcp_api_notes	特定のトピックについて API が実際にどう動作するか、ドキュメントと異なる点を説明します。コンパイル済みのテーブルから回答するため、リクエストは行いません

書き込み

フルアクセスキーが必要です。

ツール	機能
hcp_create_customer · hcp_update_customer	顧客を作成するか、顧客のフィールドを変更します
hcp_create_customer_address	顧客にサービス提供先住所を追加します
hcp_create_job	未スケジュールのジョブを作成します
hcp_add_job_line_items	ジョブに明細項目を追加します
hcp_update_job_line_item · hcp_delete_job_line_item	ジョブの明細項目を1つ変更するか、削除します
hcp_update_job_line_items	1回の呼び出しでジョブの複数の明細項目を変更します
hcp_add_job_note · hcp_delete_job_note	内部メモを追加するか、削除します。削除はジョブを再読み込みして確認します
hcp_upload_job_attachment	base64 形式で渡された写真やドキュメントをジョブに添付します。ジョブの添付ファイル一覧と照合して確認します。削除するための公開ルートはありません
hcp_upload_estimate_option_attachment	見積もりオプションにも同様に添付します。読み戻せないため、返された ID を保持してください
hcp_schedule_estimate_option	見積もりオプションの訪問を予約し、割り当てを行います。notify の既定値は false ですが、Housecall Pro が日付の近くになってから顧客にリマインダーを送る場合があります
hcp_add_job_link · hcp_add_estimate_option_link	タイトル付きリンクを添付します。アカウントにアプリケーションが必要です。ない場合は「Application not found」と返されます
hcp_lock_job · hcp_lock_jobs_by_date	ジョブを1件、または指定日以降のすべてのジョブをロックします。この API にはロック解除機能がなく、解除はダッシュボードでの操作となるため、先に確認してください
hcp_set_application_enabled	アカウントの API アプリケーションを有効または無効にします。アカウント上のすべての統合に影響します
hcp_create_webhook_subscription · hcp_delete_webhook_subscription	配信先 URL を登録または登録解除します。パートナー限定で、エンドポイントから 5xx が1回返されると登録が解除されます
hcp_update_job_input_materials	現場で使用したものとしてジョブに記録されている内容を置き換えます。リスト全体を置き換えるため、先に読み取ってください
hcp_add_job_tag · hcp_remove_job_tag	ジョブにタグを付けるか、外します
hcp_schedule_job_appointment	技術者を派遣したうえでジョブの訪問を予約し、ジョブをスケジュールします
hcp_update_job_appointment	訪問日時を変更するか、派遣する担当者を変更するか、その両方を行います
hcp_delete_job_appointment	ジョブから訪問を1件削除します
hcp_unschedule_job	ジョブの訪問とスケジュールをクリアし、スケジュールが必要な状態に戻します
hcp_dispatch_job	作業のためにチームをジョブに割り当てます。顧客に表示されるため、顧客に連絡が届くものとして扱ってください
hcp_create_estimate · hcp_add_estimate_option	複数オプションの見積もりを下書きするか、見積もりにオプションを追加します
hcp_approve_estimate_options · hcp_decline_estimate_options	1つ以上の見積もりオプションについて、顧客の回答を記録します
hcp_update_estimate_option_line_items	見積もりオプションの明細項目を置き換えます。リスト全体が置き換えられます
hcp_add_estimate_option_note · hcp_delete_estimate_option_note	見積もりオプションにメモを追加または削除します。読み戻せないため、ID を保持してください
hcp_create_lead	リードを作成します
hcp_convert_lead	リードを見積もりまたはジョブに変換します。リードはそのまま残ります
hcp_create_tag · hcp_rename_tag	タグを作成するか、名前を変更します
hcp_create_job_type · hcp_rename_job_type	ジョブタイプを作成するか、名前を変更します。削除はダッシュボードでの操作となります
hcp_create_lead_source · hcp_rename_lead_source	リードソースを作成または名前変更します。lead_source の検証リストです
hcp_create_pricebook_material · hcp_update_pricebook_material · hcp_delete_pricebook_material	価格表の資材を追加、変更、削除します
hcp_create_pricebook_material_category · hcp_update_pricebook_material_category · hcp_delete_pricebook_material_category	価格表の資材カテゴリを追加、名前変更、削除します
hcp_create_price_form · hcp_update_price_form · hcp_delete_price_form	予約可能なサービステンプレートを追加、変更、削除します

ショップのデフォルト設定

ツール	機能
hcp_get_defaults	このインストール環境に保存されているデフォルト設定を読み取ります
hcp_set_defaults	1つ以上の設定を保存するか、null を渡して設定をクリアします
hcp_get_business_profile	ビジネスプロフィールを読み取ります。ショップの概要、仕入先、価格設定、給与、メッセージに関するルールが含まれます
hcp_set_business_profile	プロフィールのセクションを1つ以上保存するか、null を渡してセクションをクリアします

3つの設定を保存します。指定がない場合の作業時間、デフォルトの到着予定時間の幅、そしてほとんどの作業で最初に使用する明細項目の名前です。これにより、同じ質問に二度答える必要がなくなります。

これらの設定はサーバーが管理するファイルに保存されます。HCP_MCP_DEFAULTS_PATH を設定すると、そのパスがファイル名として使われます。設定しない場合、Windows では %APPDATA%\housecall-pro-mcp\defaults.json、それ以外では $XDG_CONFIG_HOME/housecall-pro-mcp/defaults.json が使用され、どちらの環境変数も設定されていない場合はホームディレクトリの .config/housecall-pro-mcp/defaults.json に保存されます。この場所はマシンごとに異なり、Housecall Pro アカウントごとではありません。ファイルはインストールされたサーバーに属するため、2台のコンピューターで実行するショップは、それぞれのコンピューターでデフォルト設定を行います。このファイルの内容が Housecall Pro に送信されることはなく、受け付けるキーは固定されているため、顧客や作業に関する情報を保存することはできません。

ビジネスプロフィールは、セットアップの聞き取りを行うスキル向けに作られた、より大規模な設定です。shop、vendors、pricing、payroll、comms の5つのセクションがあり、ショップの概要、仕入先や書類の受け取り方法、利益率と端数処理のルール、給与週とコミッションのルール、送信メッセージの文体を扱います。スキルはセットアップに関する質問をする前にこれを読み込むため、同じ質問を繰り返す必要がありません。各セクションには最後に確認した日付が記録され、セクション全体が置き換えられます。そのためスキルは、セクションを読み返して確認を得てから保存します。デフォルト設定と同じファイル規則（HCP_MCP_PROFILE_PATH による上書き、defaults.json と同じ場所に置かれる profile.json）と、同じプライバシー保護方針が適用されます。マシンごとに保存され、送信されることはなく、セクションの種類は固定されており、顧客に関する情報は保存されません。また、仕入先の account_hint には、完全な口座番号に見える値を指定できません。

デスクトップバンドルのビルド

manifest.json は、このサーバーを MCP バンドルとして記述します。このバンドルをデスクトップクライアントにドラッグ＆ドロップすると、Node のインストールも設定ファイルの編集も必要なく、インストールできます。

npx -y @anthropic-ai/mcpb pack .

これにより housecall-pro-mcp-<version>.mcpb が作成されます。.mcpbignore によってビルド時の依存関係が除外されます。このルールがないと、バンドルに TypeScript コンパイラーが含まれ、サイズはほぼ3倍になります。バンドルでは、クライアント独自の設定画面で API キーの入力を求めます。また、読み取り専用モードとツールセットのリストは任意で設定できます。これらをファイルに記述する必要はありません。

登録するツールの選択

サーバーが登録するツールはすべて、クライアントが作業を始める前にコンテキストに保持する必要があります。また、一覧が長くなるほど、クライアントは重要なツールを選びにくくなります。そのため、利用するツール群を選択できます。

# Only what a reporting session needs, and nothing that can change anything
npx -y housecall-pro-mcp --read-only --toolsets=reports,invoices,customers

# A group, plus the one tool from elsewhere this session actually needs
npx -y housecall-pro-mcp --toolsets=reports --tools=hcp_list_jobs

# Exactly these two tools and nothing else
npx -y housecall-pro-mcp --toolsets=none --tools=hcp_list_jobs,hcp_get_company

オプション	効果
--read-only	変更を加えるツールを登録しません。HCP_READ_ONLY=1でも指定できます
--toolsets=a,b	指定したグループのみ登録します。HCP_TOOLSETSでも指定できます
--tools=a,b	名前で指定した個別のツールも登録します。HCP_TOOLSでも指定できます
--help	グループを一覧表示して終了します

グループ：company、customers、jobs、estimates、invoices、pricebook、 schedule、reports、admin。また、デフォルトのセットを表すall、defaultと、 グループを一切指定しないnoneもあります。

--toolsは--toolsetsに追加されます。そのため、グループを丸ごと追加せずに、そのグループに含まれていないツールを1つ追加できます。--toolsetsを指定せずにツール名を指定すると、そのツールだけが登録されます。実在しないツール名を指定すると、サーバーは該当しそうな名前を表示して停止します。要求したツールがない状態で気付かないまま起動することはありません。--read-onlyは引き続き優先されるため、書き込みツールを指定しても登録されません。

adminは、タグ、ジョブ種別、価格表の構造を保守するためのグループです。これらのレジストリを再構成する書き込み操作が含まれます。予約やレポート作成のセッションでは必要なく、デフォルトで除外すれば初期状態のツール群を小さく保てるため、デフォルトセットには含まれていません。名前で指定するか、--toolsets=default,adminを使用してください。タグやジョブ種別の一覧表示は管理操作ではありません。通常のジョブデータを解釈するために必要な読み取り操作なので、常にデフォルトセットに含まれます。

グループ名に誤りがあると、サーバーは有効なグループ名を示して停止します。ツールが欠けたまま起動することはありません。何も公開されない状態でインストールが進むと、APIに接続できない場合と見分けがつかなくなります。

--read-onlyは、キーのアクセスレベルとは別の独立した設定です。読み取り専用キーは、APIで書き込みを拒否します。この設定では、書き込みツール自体を登録しません。ライブアカウントをエージェントに見せて調査させる場合に必要なのはこの動作です。書き込みツールは単に制限されるのではなく、存在しない状態になります。

HCP_API_KEYがなくても、サーバーはキーなしで起動します。登録されるのは、Housecall Proを呼び出さないツール、つまりhcp_render_report、hcp_api_notes、およびビジネスプロフィール関連の2つのツールだけです。Housecall Proアカウントにアクセスすることはできません。これにより、APIではなくダッシュボードからエクスポートしたCSVを使う場合でもレポートレンダラーを利用でき、キーを用意する前にスキルのセットアップ時のヒアリングを実行できます。

サーバーがモデルに事前に伝えること

このプロジェクトの2つのテーブルは、READMEに残さずサーバーにコンパイルされています。READMEは人が読むものであり、モデルは読まないためです。

• 接続時の指示には、最も深刻な失敗を防ぐルールが含まれています。Housecall Proへの書き込みで2xxが返っても信頼せず、レコードを読み戻してください。
• **hcp_api_notes**は、APIの実際の動作についての平易な質問に回答します。ルート、フィールド、または実行しようとしていた操作について、上記の2つのセクションと同じ検証済みテーブルを参照します。リクエストは行わないため、コストはかかりません。実行できないと結論付ける前や、成功と報告されたものの何も変わっていないように見える書き込みの後に質問してください。
• 同じテーブルは、MCP リソース（hcp://api-notes/quirksおよびhcp://api-notes/phantom-routes）としても公開されています。ツール呼び出しを使わずにリソースを読み取れるクライアントで利用できます。

動作

書き込みツールは、フルアクセスキーでのみ動作します。読み取り専用キーで呼び出すと、意図しない操作を行う代わりに、理由を説明する簡潔なメッセージを返して失敗します。

すべてのツールには仕様のアノテーションが付いているため、クライアントは名前から推測しなくても、読み取りと書き込み、書き込みと削除、またはいずれかと顧客に連絡する操作を区別できます。hcp_dispatch_jobと見積もりの承認・拒否ツールには、顧客に通知する可能性があることを示すアノテーションが付いています。実際に通知される可能性があるためです。 すべてのツールは、結果をテキストだけでなく構造化データとしても返すため、レコードを必要とするクライアントは、文章から解析して取り出す必要がありません。また、ツールの一覧には出力スキーマも宣言されているため、呼び出す前に tools/list からフィールド名、型、階層構造を確認できます。Housecall Pro のレコードを変更せずにそのまま返すツールでは、意図的にスキーマを宣言していません。こちらで管理していないフィールドを記述すると、気づかないうちに古くなってしまうためです。

このツールは、ユーザーに代わってメール、テキストメッセージ、見積もりを送信することはありません。見積もりを作成しても下書きのままで、送信する場合は、Housecall Pro 内でユーザー自身が明示的に操作する必要があります。

レポートは閲覧中の場所に表示されます。MCP Apps に対応したクライアント（現在は Claude と Claude Desktop で、Claude Code は非対応）では、hcp_render_report により会話内に直接表示されます。並べ替えやフィルタリングができる同じレポートを表示し、行を選択してチャットに戻すこともできます。ダウンロードもファイルの書き込みも行われません。それ以外の環境では、従来どおりツールがレポートを単独で完結する HTML ファイルとして返すため、この機能の有無に依存しません。どちらの形式でもレポートはネットワークリクエストを送信しません。そのため、これらのクライアントが適用する厳格なコンテンツポリシーの下でも実行できます。クライアントが対応していると表示されているのに何も表示されない場合は、as_file を指定してレポートをもう一度依頼すると、ファイル版が返されます。

作業員の派遣は顧客に表示されます。 hcp_dispatch_job はジョブに作業員を割り当てます。この処理は顧客にも表示されるため、Housecall Pro から顧客に、誰が来るのか、また誰かが向かっていることが通知される場合があります。どちらの場合も送信内容の確認は行われていないため、送信されないと決めつけず、顧客に届くものとして扱ってください。

見積もりオプションへの回答の記録は、顧客に問い合わせを送ることではなく、顧客の回答を事業者が記録することです。Housecall Pro では、その結果を「pro approved」または「pro declined」と呼び、hcp_approve_estimate_options と hcp_decline_estimate_options がその内容を記録します。実行時にメールもテキストメッセージも送信されませんでした。ただし、これはお使いのアカウントについての保証ではありません。Housecall Pro の自動化機能や通知設定は、個々の呼び出しの内容にかかわらず独立して動作するため、あるアカウントの設定が別のアカウントにも当てはまるとは限りません。承認済みオプションをジョブにコピーするよう設定されたアカウントでは、オプションを承認するとジョブが作成され、そのジョブ名が応答に含まれます。

複数の明細項目の変更は 1 回の呼び出しで行います。 hcp_update_job_line_items は、リスト全体を 1 回のリクエストで Housecall Pro に渡します。hcp_update_job_line_item は行ごとに 1 回リクエストするため、複数回実行すると途中で止まり、ジョブの価格が一部だけ変更された状態になることがあります。変更する行が 1 行だけの場合は前者を、複数行の場合は一括更新ツールを使用してください。

ジョブの予約は 1 回の呼び出しで行います。 ジョブに予約を作成すると、そのジョブのスケジュールも設定されるため、hcp_schedule_job_appointment で作業の予約と派遣をまとめて行えます。ジョブは「スケジュールが必要」という状態ではなくなり、訪問予定は指定した作業員に割り当てられます。同じジョブに対して再度呼び出すと、2 回目の訪問を追加できます。すべての予約には少なくとも 1 人の作業員が必要です。作業員を誰も指定しない予約は送信されず、ここで拒否されます。

hcp_update_job_appointment で訪問予定を移動すると、ジョブのスケジュールも同時に変更されるため、再予約も 1 回の呼び出しで行えます。予約を取り消すには、1 件の訪問予定には hcp_delete_job_appointment を、すべての訪問予定を取り消してジョブ全体を「スケジュールが必要」の状態に戻すには hcp_unschedule_job を使用します。

顧客に日時を提案する前に、hcp_get_schedule_availability でアカウントの営業時間を確認し、hcp_list_booking_windows で予約可能と報告されている時間枠を確認できます。これにより、アカウントの実際の運用に合った日時を提案できます。

これらの呼び出し自体が顧客にメールやテキストメッセージを送信することはありません。Housecall Pro が送信するのは、日程が近づいたときの予約リマインダーであり、これはこのサーバーではなく、お使いのアカウントの設定によって決まります。Housecall Pro に設定した自動化機能は、このサーバーの管理外で独立して動作します。 書き込みに失敗しても自動で再試行されないため、ネットワークの一時的な問題で同じレコードが重複して作成されることはありません。

API キーが送信されるのは api.housecallpro.com のみです。このサーバーが行うその他のリクエストは、「更新」に記載されているバージョン確認だけで、アカウントデータは送信されません。

キーの送信先

設定するキーは 1 つで、送信先のホストも 1 つだけです。

• Housecall Pro API キー（HCP_API_KEY）は api.housecallpro.com のみに送信されます。Housecall Pro アカウントから読み取られた情報が、ほかの場所に送信されることはありません。

このサーバーが行うその他のリクエストは、「更新」に記載されているバージョン確認だけで、製品名とインストール済みバージョン以外の情報は送信されません。

制限事項

仕様による制限もいくつかあります。

予約はジョブに紐付いています。 アカウント全体の予約一覧はないため、訪問を確認するにはジョブごとに取得します。「今週のすべての予約」ではなく、ジョブの予約を取得してください。アカウント独自のスケジュールはアカウント全体を対象に取得できます。hcp_get_schedule_availability は営業時間を返し、hcp_list_booking_windows は予約可能として表示される時間枠を返します。

訪問時間枠の長さは、Housecall Pro が受け付ける値でなければなりません。 0、15、20、60、120、180、240 分のいずれかで、0 は正確な時刻を意味します。書き込み時にほかの値は拒否されるため、予約ツールでは任意の数値ではなく、受け付けられる長さのリストを提示します。

予約は取り消せますが、ジョブは削除できません。 hcp_unschedule_job は訪問を取り消してスケジュールをクリアし、ジョブを「スケジュール設定が必要」の状態に戻します。顧客、項目、メモはそのまま残ります。Housecall Pro の API にはジョブを削除するエンドポイントがないため、誤って作成したジョブは Housecall Pro 上で完了扱いにします。

顧客住所は追加のみ可能です。 hcp_create_customer_address で住所を追加できますが、その後に変更または削除するエンドポイントはありません。追加する前に正しいことを確認してください。誤った住所は Housecall Pro 上で修正します。

ジョブからタグを外す場合は、1 回につき 1 つです。 hcp_remove_job_tag にはジョブとタグの指定が必要です。ジョブのすべてのタグを一度に消去する呼び出しはありません。また、タグの変更を許可する権限が付与されたキーも必要です。そのため、ここで 401 が返される場合は、機能がないのではなく、キーのアクセスレベルが原因です。

チェックリストはジョブまたは見積もりを指定して取得する必要があります。 アカウント内のすべてのチェックリストを一覧表示する方法はありません。結果が空の場合は、エラーではなく、そのレコードにチェックリストが設定されていないことを意味します。

タグは作成と名前変更ができますが、削除はできません。 アカウントからタグを削除するには、Housecall Pro 上で操作します。タグは慎重に作成してください。

更新

起動時に、サーバーは hcpapi.com に新しいバージョンがあるか確認します。このリクエストで送信されるのは製品名とインストール済みバージョンだけで、それ以外の情報は送信されません。新しいバージョンがある場合、次のツールの応答で一度だけ通知されます。確認を完了できない場合も、サーバーはそのまま動作を続けます。

更新するには、クライアントのインストールコマンドを再実行してください。「インストール」にある npx のセットアップでは、公開済みの最新バージョンが取得されます。クライアントが古いキャッシュ済みコピーを使い続ける場合は、引数を ["-y", "housecall-pro-mcp@latest"] に変更すると、最新リリースを強制的に取得できます。

トラブルシューティング

401 Unauthorized。 キーが読み取り専用なのに書き込みツールを呼び出したか、キーを作成した従業員にそのデータへのアクセス権がありません。フルアクセスキーを作成するか、その従業員の権限を確認してください。

期待したデータが取得できず、結果が空になる。 通常は同じ原因です。従業員に紐付いたキーで取得できるのは、その従業員が閲覧できるデータのみです。

クライアントにツールが表示されない。 node --version で Node 18 以降がインストールされていることを確認してください。また、HCP_API_KEY がシェルではなく、MCP サーバーの env ブロック内に設定されていることを確認してください。

さらに詳しく

このサーバーは Housecall Pro API 自体を対象としています。現在、その上位レイヤーとなるレポート作成やエクスポートのワークフロー、価格表ツール、Webhook の設定機能を開発中です。ご興味があれば、[email protected] までメールでお問い合わせください。準備ができ次第、お知らせします。

問題とプルリクエスト

バグ報告や機能リクエストは課題トラッカーで歓迎します。投稿は多ければ多いほど助かります。アシスタントに何を依頼し、どのような結果が返ってきたかを記載してください。

プルリクエストは自動的にクローズされます。リリースは、プルリクエストでは実行できない内部テストスイートで検証されるため、ここで適切にレビューする方法はありません。問題で不具合をお知らせいただくほうが、パッチを提供いただくよりも早く修正できます。

ライセンス

MIT、著作権者 HCP API。Housecall Pro とは無関係の独立したプロジェクトです。 「Housecall Pro」はその所有者の商標であり、ここでは互換性を説明する目的でのみ使用しています。