housecallpro-mcp

Housecall Pro MCP

Claude を Housecall Pro の顧客側、つまり請負業者（HVAC、配管、電気工事、清掃業者）からメールやテキストで送られてくる見積もりまたは請求書のリンクに接続する、Model Context Protocol サーバーです。

警告

AI が開発したプロジェクトです。 このコードベースは Claude Code によって構築され、現在も積極的に保守されています。人間による実装の監査は行われていません。使用する前に、すべてのコードとツールの権限を確認してください。

事業者側ではなく、顧客側です

Housecall Pro には2つのインターフェースがあり、互いに共有するものはありません。

	公開 API	顧客ポータル（このリポジトリ）
ホスト	api.housecallpro.com	app.housecallpro.com
対象	Housecall Pro を利用する事業者	その事業者の顧客
認証	事業者アカウントの API キー	請負業者から送られたリンク
ドキュメント	docs.housecallpro.com	docs/HOUSECALLPRO-API.md

Housecall Pro で事業を運営している場合は、代わりに公開 API を利用してください。このサーバーは、誰かの顧客として利用するためのものです。

できること

• 「配管業者から、タンクレス給湯器のフラッシュ洗浄はいくらと見積もられましたか？」
• 「あの見積もりの項目を、1つずつ教えてください。」
• 「346ドルのうち、税金はいくらですか？」
• 「まだ返事をする必要がありますか？」
• 「オプション2を辞退してください。」

インストール

npx -y @chrischall/housecallpro-mcp

請負業者から送られたリンクを使って設定します。

HOUSECALLPRO_LINK='https://pro.housecallpro.com/mobile_estimate/XXXXXXXXXX'

見積もりと請求書のリンクは、短縮形式と長い形式のどちらも使用できます。pro.housecallpro.com/mobile_estimate/… と /mobile_invoice/…、または client.housecallpro.com/estimates/… と /invoices/… です。複数のドキュメントを設定する場合：

HOUSECALLPRO_LINKS='[{"label":"tankless","url":"…"},{"label":"hvac","url":"…"}]'

その後、すべてのツールで省略可能な link セレクターを使用できます。1つ設定しておけば、これを指定する必要はありません。

重要

リンクはベアラー認証情報です。 リンクを持っている人は誰でもドキュメントを閲覧でき、見積もりの場合は辞退することもできます。リンクは環境から読み込まれ、ログに記録されることも、ツールの結果として返されることもありません。housecallpro_list_links が報告するのはラベルのみです。

確認

辞退する前に確認を求めます。確認プロンプトを表示できるクライアント（Claude Code）では、確認プロンプトが表示されます。確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）では、最初の呼び出しでは何も辞退せず、プレビューと confirmToken を返します。そのトークンを使って再度呼び出した場合にのみ操作が実行され、見積もりがプレビュー時の内容と一致している場合に限られます。

変数	デフォルト
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込み操作を行う際の動作です。ask-user：2段階で行います。最初の呼び出しでは何も行わず、プレビューとトークンを返します。モデルは再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく2段階で行いますが、モデルはプレビューを自分で確認した後にトークンを使用できます。refuse：このようなクライアントでは書き込み操作を拒否します。プロンプトを表示できるクライアント（Claude Code）では、MCP_CONFIRM_ELICITATION=off に設定しない限り、常に実際のプロンプトが表示されます。認識されない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off に設定すると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の動作が適用されます。プロンプトを表示できるとされているのに実際には表示しないクライアント（書き込み処理が停止する opencode 2.0.x）で設定してください。それ以外の値は on として扱われ、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。トークンをサーバーの再起動後も有効にする必要がある場合にのみ設定してください。

ツール

ツール
housecallpro_get_estimate	明細項目、合計、税金、会社、承認状態
housecallpro_get_invoice	金額、小計、税金、未払い残高、支払い可能かどうか
housecallpro_get_company	業者：電話番号、メールアドレス、ウェブサイト、到着時間帯
housecallpro_list_links	設定済みリンク、ラベルのみ
housecallpro_decline_estimate	辞退オプション — 先に確認を求めます
housecallpro_approve_estimate	常に拒否し、その理由を説明します
housecallpro_healthcheck	接続可能かどうか、およびリンクが引き続き解決されるかどうか

レスポンス形式（view）

housecallpro_get_estimate と housecallpro_get_invoice は view: 'compact' | 'raw' を受け取り、デフォルトは compact です。これは @chrischall/mcp-utils の フリート用語です。

段階	得られるもの
compact (デフォルト)	要約：明細項目、合計、税金、会社、承認状態 — 金額は *_cents と *_usd の両方で表示
raw	上流のドキュメントをそのまま表示（見積もりの場合は約4.8 KB）。{object, data} のラッパーと表示フラグも含みます

意図的に full の段階はありません。full は「このサーバーが理解するすべてのフィールドを、何も省略せずに含める」という意味です。このサーバーが理解するフィールドは、要約に記載されているものとまったく同じなので、別の名前を付けた compact にすぎません。その先にあるのは上流のドキュメントであり、それが raw です。スキーマで、別の値に暗黙に別名を付けるような項目を提示すべきではありません。

上流の形式が大きく変化し、投影が成り立たなくなった場合は、空の要約ではなく、ドキュメント全体を返します（stderr に警告を出します）。空の要約は、内容が何もない見積もりと区別できないためです。

見積もりと請求書は異なるドキュメントです

トークンの形式（見積もりは129文字、請求書は32文字）とエンドポイントが異なります。クライアントはリクエストを送る前に形式を確認し、誤ったツールを指すトークンを拒否します。説明のない404をそのまま返すことはありません。

請求書には 明細項目も税金フィールドもありません。支払い済みの請求書はポータルで要約として表示され、APIもその内容をそのまま返すため、tax_usd は total - subtotal から算出されます。is_paid はステータス文字列ではなく、残高に基づきます。

金額は2つの形式で返されます

上流のAPIは 整数のセント単位で返します。ポータルで $346.39 と表示される見積もりは、total_amount: 34639 として届きます。そのまま報告するとすべての金額が100倍に過大表示されるため、各金額フィールドは *_cents（そのままの値）と *_usd（換算値）の両方で出力されます。tax.rate は割合（0.0825 = 8.25%）であり、換算されることはありません。

この2つを組み合わせることが投影の 目的 なので、この形式があるのは compact のみです。view: 'raw' は上流のドキュメントであり、金額は整数のセント単位で、ドル換算値は含まれません。total_amount: 34639 は $346.39 です。view パラメーターの説明にも、呼び出し箇所でその旨が記載されています。

見積もりを承認できない理由

housecallpro_approve_estimate は常に拒否します。これは意図的な動作です。

承認では、response_token を送信します。これは、estimates_customer_approvals アクション用にページ内で生成される reCAPTCHA v3 トークンです。サーバー側のクライアントは生成できず、ブラウザーブリッジのトランスポートでも生成できません。ブリッジは fetch 呼び出しを発行しますが、ページのJSを実行するわけではありません。辞退にはそのようなトークンが不要なため、辞退は機能しますが、承認は機能しません。

拒否されるリクエストを送信すること、あるいはさらに悪いことに、拒否されず見積もり価格に拘束される可能性を避けるため、ツールは拒否し、ブラウザーで承認するよう案内します。

辞退するには、先に確認が必要です（確認を参照）。見積もりを読み取り、選択肢にないIDや、すでに決定済みのIDは拒否し、送信前に送信内容を正確に表示します。実際に辞退した後は、見積もりを再読み込みして、オプションの実際のステータスを報告します。2xx は書き込みが反映された証明にはならないためです。

MCP なしの場合

skills/housecallpro を使うと、サーバーがインストールされていないスクリプトやマシンから、通常の curl と jq を使って同じ情報を読み取れます。こちらもブラウザブリッジは使用しません。

ブラウザブリッジなし

この環境のほかの多くとは異なり、app.housecallpro.com にはボット対策の壁がないため、通常の curl でも 200 が返ります。そのため、このサーバーは HTTPS 経由で直接接続し、@fetchproxy/server への依存がなく、拡張機能やサインイン済みのタブも不要です。また、リモートコネクターとして簡単にホストできます。リンクは環境変数ではなくツールの引数として渡されるため、設定するシークレットもありません。

含まれない機能

• 決済とカード。 意図的に対象外としています。
• アカウントレベルのポータル。 Housecall Pro には、1 つの業者からのすべての書類をまとめて表示する、OTP／マジックリンク方式の顧客ポータルがあります。これは書類ごとのリンクよりも明らかに優れた方法です。導入には人がワンタイムコードを受け取る必要があるため、今回の初回リリースには含めず、次に追加する機能として最適です。

開発

npm install
npm run build
npm test

ライセンス

MIT