Housecall Pro Mcp

Housecall Pro MCP

Housecall Pro 公開 API 用のターミナル CLI および Claude Code プラグインです。 顧客の管理、作業の予約、見積もりの作成、請求書の追跡、リードへの対応などを、すべて自然言語で行えます。

---

必要条件

• Housecall Pro の MAX プランアカウント
• Housecall Pro API キーまたは OAuth 認証情報（取得方法）

---

インストール

このツールの使用方法は 2 つあります。ワークフローに合った方法を選んでください。

---

オプション A — hcpro ターミナル CLI

単独で使えるターミナルツールです。curl コマンド 1 つで必要なものをすべてインストールでき、手動での設定は不要です。

必要条件： Claude Code がインストール済みであること — macOS と Linux のみ（Windows はサポートされていません）

1. インストール

curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

~/.local/bin が $PATH に含まれていない場合、インストーラーが追加するコマンドを表示します。

特定のバージョンを固定するには：

HCPRO_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

2. Housecall Pro に接続する

hcpro auth login

プロンプトが表示されたら、認証方法を選択してください：

• API Key (推奨) — Housecall Pro API キーを貼り付けます
• OAuth 2.0 (上級者向け) — クライアント ID とシークレットを入力します。認証用のブラウザーウィンドウが開きます

ほとんどのユーザーには API キーを推奨します。 OAuth 2.0 を使用するには、このコマンドを実行する前に、HCP 開発者ダッシュボードのアプリ設定で http://localhost:7891/callback を許可されたリダイレクト URI として登録する必要があります。この手順を省略すると、認証に失敗します。

API アクセスには MAX プランが必要です。403 エラーが発生した場合は、プランを確認してください。

3. Claude に接続する

hcpro auth claude login

プロンプトが表示されたら、Claude の認証方法を選択してください：

• API Key — Anthropic API キーを貼り付けます（トークンごとに課金）
• Subscription — Claude Code を通じて、既存の Claude.ai Pro/Max サブスクリプションを使用します

Claude Code にすでにログインしている場合でも、この手順は必要です。再認証ではなく、hcpro が使用する認証方法を登録するだけです。すでにログインしている場合、Subscription を選択すればすぐに完了します。

4. 使用を開始する

単発クエリ：

hcpro "list my jobs today"
hcpro "find customer John Smith"
hcpro "show all open invoices"

対話型セッション：

hcpro chat

認証状態を確認する

hcpro auth status

認証情報を削除する

hcpro auth logout          # remove HCP credentials
hcpro auth claude logout   # remove Claude credentials from hcpro (does not sign out of Claude Code itself)

hcpro を更新する

インストールスクリプトを再実行します。既存のバイナリがその場で置き換えられます：

curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

hcpro をアンインストールする

rm -rf ~/.local/lib/hcpro ~/.local/bin/hcpro

ヘルプを表示する

hcpro --help
hcpro auth --help
hcpro auth claude --help

---

オプション B — Claude Code プラグイン

Claude Code の中だけで作業したいユーザー向けです。

必要条件： Claude Code がインストール済みであること、Node.js 20+

ステップ 1 — マーケットプレイスを登録する

/plugin marketplace add toducthanh/housecallpro-mcp

現在のプロジェクトだけに適用するには --scope local を追加します。すべてのリポジトリ共同作業者と共有するには --scope project を追加します。

ステップ 2 — プラグインをインストールして設定する

/plugin を実行 → Marketplaces タブを開く → toducthanh を選択 → Browse plugins → housecallpro-mcp を探す → インストールします。

インストール後、Installed タブに移動 → housecallpro-mcp を選択 → Configure options を選び、認証情報を入力します。

API キー認証 (推奨)：

オプション	値
認証方法	apikey
Housecall Pro API キー	API キー

OAuth 2.0 (上級者向け)：

オプション	値
認証方法	oauth
Housecall Pro クライアント ID	OAuth クライアント ID
Housecall Pro クライアントシークレット	OAuth クライアントシークレット
Housecall Pro OAuth トークン	OAuth アクセストークン

このプラグインで OAuth を使用するには、アクセストークンを手動で取得する必要があります（例：HCP デベロッパーダッシュボードから取得）。トークンの自動更新には対応していません。トークンの有効期限が切れたら、Configure options で手動更新する必要があります。API キーの使用を推奨します。

CLI からもインストールできます（デフォルトはユーザースコープです）。

/plugin install housecallpro-mcp@toducthanh

続いて、/plugin → Installed タブ → Configure options から認証情報を設定します。

/reload-plugins を実行して、プラグインを有効にします。

動作を確認する

Claude Code 内で実行します。

/skills    ← should list housecallpro
/mcp       ← should show housecallpro connected

続いて、実際にテストします。

Use the housecallpro MCP to get my company information

---

API キーの取得方法

1. Housecall Pro アカウントにログインします
2. App Store → API Key Management → Generate に移動します
3. キーをコピーし、安全に保管します

API アクセスには MAX プランが必要です。403 エラーが発生した場合は、プランを確認してください。

---

使い方 — プロンプトの例

顧客

List my first 10 customers
Find customer named "John Smith"
Create a customer Jane Doe with email [email protected] and mobile +1 555 123 4567
Get all addresses for customer {customer_id}
Fetch all customers with fetch_all true and tell me the total count

予約とスケジュール管理

Book a job for customer {customer_id} at address {address_id} on 2025-05-01 at 9am for 1 hour
Find customer John Smith, get his address, create a job and schedule it for next Monday 9am
Reschedule job {job_id} to 2025-05-10 at 2pm and notify the customer
Dispatch job {job_id} to employee {employee_id}
List all scheduled jobs for this week
List all unscheduled jobs
Get available booking windows for the next 7 days

見積もりと請求書

Create an estimate for customer {customer_id} at address {address_id}
Add an option "Standard Package" with a labor line item to estimate {estimate_id}
Approve estimate option {option_id}
List all open invoices
Get all invoices for job {job_id}
List invoices created between 2025-01-01 and 2025-03-31

リード

Create a lead for customer {customer_id}
List all open leads
Convert lead {lead_id} to a job

レポートと一括処理

Fetch all completed jobs with fetch_all true for Q1 2025
Fetch all customers with fetch_all true and count how many have no address
List all employees
Get company information

---

ワークフローガイド

既存の顧客の作業を予約する

AI が次のステップを自動的に連携して実行します。

1. list_customers → customer_id を検索
2. list_customer_addresses → address_id を検索
3. create_job → 作業を作成
4. update_job_schedule → スケジュールを設定
5. dispatch_job → 技術者を割り当て（任意）

プロンプトの例：

Find customer John Smith, get his first address, create a job there
scheduled for 2025-05-01 9am-10am with 60 min arrival window,
notify the customer, and dispatch to employee Mike Johnson

新規顧客の作業を予約する

Create a new customer Sarah Connor, phone +1 555 999 0000,
add her address 123 Main St Austin TX 78701,
then book a job there for 2025-05-02 at 2pm for 2 hours

オプション付きの見積もりを作成する

見積もりは 2 層構造です。まず オプションを作成し、その各オプション内に明細項目を追加します。

Create an estimate for customer {customer_id} at address {address_id},
add an option called "Standard Package" with a labor line item at $150,
then approve it

リードを作業に変換する

Create a lead for customer {customer_id},
show me the pipeline statuses,
move it to the next status,
then convert it to a job and schedule it for next Monday at 10am

---

フィールドの形式

フィールド	有効な形式	無効な形式
日付	"2025-05-01T09:00:00"	"05/01/2025"、"next Monday"
電話番号	"+1 555 123 4567"	"555-PLUMBER"
作業ステータス	"scheduled"、"completed" など	"done"、"pending"
金額	整数のセント単位 — $150 = 15000	150.00
ID	空でない文字列	""（空）

有効な作業ステータスの値：unscheduled · scheduled · in_progress · completed · canceled

---

すべてのページを取得する

複数の一覧表示ツールは、fetch_all: true を指定すると、すべてのページを自動的に取得できます。

Fetch all customers with fetch_all true
Fetch all completed jobs with fetch_all true from 2025-01-01 to 2025-03-31

対応ツール：list_customers、list_jobs、list_estimates、list_leads、 list_invoices、list_employees、list_events、list_tags、list_materials、 list_pricebook_services

デフォルトでは 20 ページ（約 200 件）まで取得します。さらに大きなデータセットを取得するには、page と page_size を明示的に指定してください。

---

エラーリファレンス

エラー	原因	対処方法
HCP API Error (401)	API キーが無効、または未設定です	HOUSECALL_API_KEY を確認してください
HCP API Error (403)	MAX プランではありません	プランをアップグレードするか、HOUSECALL_AUTH_METHOD を確認してください
HCP API Error (404)	ID が間違っているか、エンドポイントを利用できません	ID を再確認してください
HCP API Error (422)	必須フィールドがありません	必須パラメーターを確認してください
HCP API Error (429)	レート制限に達しました	サーバーが自動で再試行します。待ってから再試行してください
Must be ISO 8601 format	日付形式が正しくありません	"2025-05-01T09:00:00" を使用してください
Must be a valid phone number	電話番号が無効です	"+1 555 123 4567" を使用してください
ID cannot be empty	ID に空文字列が指定されています	先に正しい ID を取得してください
/skills に何も表示されない	プラグインが読み込まれていません	手順 1 と 2 を再実行し、その後 /reload-plugins を実行してください
/mcp に housecallpro が表示されない	MCP が起動していません	/plugin → Installed → Configure options に移動し、認証情報を確認してください
HCP credentials not configured	hcpro auth login が実行されていません	hcpro auth login を実行してください
Claude credentials not configured	hcpro auth claude login が実行されていません	hcpro auth claude login を実行してください
claude binary not found	Claude Code がインストールされていません	claude.ai/code からインストールしてください

---

既知の制限事項

• パイプライン は前方向にのみ進みます。順序が前のステータスには設定できません
• 空き状況／予約枠のエンドポイント — 空き枠の取得には get_booking_windows を使用してください
• 見積もり では Options → Line Items を使用します（Jobs のように直接指定することはできません）
• 資材 には material_category_uuid が必要です。先に list_material_categories を呼び出してください
• 支払い処理 — 公開 API では利用できません。HCP ダッシュボードを使用してください
• fetch_all はデフォルトで 20 ページに制限されています
• レート制限 — HCP から公開されていません。サーバーはバックオフを行い、最大 3 回まで自動で再試行します

---

ツールの概要

Housecall Pro API の全リソースにわたる 70 以上のツール：

リソース	ツール
顧客	一覧表示、取得、作成、更新、住所
ジョブ	一覧表示、取得、作成、スケジュール設定、ディスパッチ、明細、メモ、タグ、ロック、請求書
見積もり	一覧表示、取得、作成、オプション、明細、承認
請求書	一覧表示、取得、プレビュー
リード	一覧表示、取得、作成、変換、明細
従業員	一覧表示
タグ	一覧表示、作成、更新、削除
イベント	一覧表示、取得
資材	一覧表示、作成、更新、削除
価格表	サービス、価格フォーム
パイプライン	ステータス、ステータスの更新
ルート	一覧表示
会社	取得、スケジュール枠、予約枠
Webhook	登録、登録解除
アプリケーション	取得、有効化、無効化

---

開発

git clone https://github.com/toducthanh/housecallpro-mcp
cd housecallpro-mcp
npm install
npm run generate-types   # generate types from housecall_v1.yaml
npm run build
npm run dev

素早く反復する場合： インストールせずに、現在のセッションでのみプラグインを読み込みます。

claude --plugin-dir .

セッション内で /reload-plugins を使用すると、再起動せずに変更を反映できます。

CLI 開発

cd cli
bun install
bun test                  # run all tests
bun run dev               # run CLI in dev mode (no build needed)

開発モードでコマンドを実行する：

bun run src/index.ts auth status
bun run src/index.ts "list my jobs today"
bun run src/index.ts chat

バイナリをローカルでビルドする：

bun run build:darwin-arm64   # macOS Apple Silicon
bun run build:darwin-x64     # macOS Intel
bun run build:linux-x64      # Linux x64
bun run build:linux-arm64    # Linux ARM

バイナリは ../dist/ に出力されます。

インストールフロー全体をテストする：

# Register the local marketplace scoped to this project only
claude plugin marketplace add ./ --scope local

# Then in Claude Code: /plugin → Discover → install housecallpro-mcp → Configure options

テスト後にクリーンアップするには：

オプション A — マーケットプレイスを削除する（プラグインも削除されます）：

claude plugin marketplace remove toducthanh --scope local

オプション B — 先にプラグインをアンインストールし、その後マーケットプレイスを削除する：

# Via CLI
claude plugin uninstall housecallpro-mcp --scope local

# Or via UI: /plugin → Installed tab → select housecallpro-mcp → Uninstall

その後、マーケットプレイスを削除します：

# Via CLI
claude plugin marketplace remove toducthanh --scope local

# Or via UI: /plugin → Marketplaces tab → select toducthanh → Remove

---

リンク

• Housecall Pro API ドキュメント
• npm パッケージ
• GitHub リポジトリ
• GitHub リリース
• Model Context Protocol
• Claude Code

---

ライセンス

コードは General Public License v3.0 の下で公開されています。