honeybook-mcp

HoneyBook MCP

Claude を HoneyBook のクライアントポータルに接続し、結婚式の業者から送られた契約書や請求書に自然言語でアクセスできる Model Context Protocol サーバーです。

警告

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

できること

Claude に次のようなことを尋ねられます。

• 「マジックリンクを貼り付けてください。HoneyBook ポータルに接続します。」
• 「未署名の契約書をすべて見せてください。」
• 「来月中に支払い期限を迎える請求書はありますか？」
• 「Silk Veil Events との契約書を要約してください。」
• 「カメラマンとの契約書に署名するためのディープリンクを教えてください。」
• 「今月プランナーから届いたものは何ですか？チェックリストを読み上げてください。」
• 「Ivy の最後のメッセージに返信して、リハーサルの時間を尋ねてください。」
• 「次のプランナーとの Zoom はいつですか？リンクも教えてください。」
• 「これまでにいくら支払いましたか？残りはいくらですか？」

要件

• Claude Desktop または Claude Code
• Node.js 22 以降
• HoneyBook を利用している結婚式の業者から届くマジックリンクメール
• ContextMint Bridge ブラウザー拡張機能 — Chrome では、リリースページから chrome の zip をダウンロードし、展開せずに読み込んでください（chrome://extensions → デベロッパーモード → パッケージ化されていない拡張機能を読み込む）。Safari にはまだ対応していません（公開ダウンロードのない ContextMint アプリ内に同梱される予定です）。現時点では Chrome を使用してください。use_magic_link が、ログイン済みの業者ポータルのタブからセッションのスナップショットを取得するために使用します。

利用規約の確認

この MCP サーバーを使用することで、以下の内容を確認し、同意したものとみなされます。

1. このサーバーがアクセスするのは、お客様ご自身の HoneyBook ワークスペースです。 すべてのリクエストは、ContextMint Bridge 拡張機能を介して、お客様がサインインしているブラウザーセッションから送信されます。他のユーザーのワークスペースにはアクセスしません。また、アクセスすることもできません。

2. このサーバーの利用には、HoneyBook の利用規約が適用されます。 honeybook.com を直接利用する場合と同様です。特に関連する条項は次のとおりです。

本サービスの利用に関連して、データマイニング、ロボット、スクレイピング、または類似のデータ収集・抽出手法を使用したり、それらに従事したりしてはなりません。

また、ユーザーは「本サービスまたは本サービスのコンテンツに基づいて、改変、複製、フレーム表示、スクレイピング、レンタル、リース、貸与、販売、配布、または二次的著作物の作成」を行うことはできません。

このサーバーでツールを呼び出すたびに、メンテナーが2026-05-23に確認したこれらの規約に同意することになります。HoneyBook の利用規約は、データマイニングとスクレイピングを広く禁止しています。この MCP は非公式の自動化ツールであり、HoneyBook は例外を認めていません。

3. 個人による単一事業での利用に限ります。 このプロジェクトは、HoneyBook, Inc. と提携、推奨、後援、または協力関係にありません。個人の HoneyBook アカウント所有者が自身のワークスペースを操作するための自動化ツールです。他の事業者のために使用したり、HoneyBook のディレクトリやテンプレートのコンテンツを一括抽出したり、このツールを基盤とする二次的な SaaS 製品を作成したりしないでください。

4. 安定性は保証されません。 このサーバーは、HoneyBook が予告なく変更する可能性のある内部エンドポイントを呼び出します。動作しなくなる場合があります。

5. ご自身の HoneyBook アカウントに関連してこのサーバーを使用したことによる結果については、すべてご自身の責任となります。 レート制限、アカウントへの警告、停止、または HoneyBook によるあらゆる措置が含まれます。HoneyBook は自動化されたトラフィックを検出し、お客様の IP アドレスやワークスペースをブロックする場合があります。HoneyBook から利用について異議を申し立てられた場合は、このサーバーの使用を中止してください。

このセクションは、メンテナーが誠実に規約を要約したものであり、法的助言ではありません。また、HoneyBook の実際の利用規約を変更したり、これに優先したりするものではありません。

インストール

ソースから

git clone https://github.com/chrischall/honeybook-mcp.git
cd honeybook-mcp
npm install
npm run build

Claude Desktop の設定（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "honeybook": {
      "command": "node",
      "args": ["/absolute/path/to/honeybook-mcp/dist/bundle.js"]
    }
  }
}

環境変数は不要です。以下のオプションは、書き込みの確認方法を調整するものです。確認を参照してください。

セッション

HoneyBook には、公開されているクライアントポータル API がありません。この MCP は、ContextMint Bridge ブラウザー拡張機能を介して、ベンダーのマジックリンクをクリックした後にブラウザーに保存されるものと同じ認証状態を再利用します。

初回のセットアップ：

1. ContextMint Bridge をリリースページからインストールします。Chrome では、chrome zip を展開した状態で読み込みます。Safari にはまだ対応していません（公開ダウンロードがない ContextMint アプリに同梱される予定です）。当面は Chrome を使用してください。 ContextMint Bridge は、同じメンテナーによる fetchproxy ブラウザー拡張機能の新しい名称です。fetchproxy 自体の README（fetchproxy#extension）からも案内されています。ソースはnullnet-app/contextmint-bridgeで公開されています。自分でビルドするか、公開リリース zip を隣に公開されている .sha256 ファイルと照合してください（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。
2. 通常のブラウザーで各ベンダーのマジックリンクをクリックします。これにより、各ベンダーの *.hbportal.co ポータルにサインインできます。

ベンダーごとの有効化：

1. ベンダーのポータルタブ（メールで届いたマジックリンクのページ）が開いていることを確認します。
2. Claude で use_magic_link を呼び出し、マジックリンクの URL を渡します。このツールは ContextMint Bridge 拡張機能に、ページの localStorage["HONEYBOOK_REACT_CURR_USER"] から認証フィールドを取得してスナップショットするよう依頼し、その後ブリッジを閉じます。タブが開いていてサインイン済みであればよく、進行中のリクエストから何かを読み取ることはありません。ヘッドレスブラウザーも起動しません。
3. その他のすべてのツールは、デフォルトで直近に有効化されたセッションを使用します。複数のベンダーが有効な場合は、origin を明示的に渡してください。

セッションはメモリに保存され、MCP の再起動後も維持されるよう ~/.honeybook-mcp/sessions.json（モード 0600）にも永続化されます。セッションの有効期限が切れたら、use_magic_link を再実行してください。

アンケート（「flow」）リンク

ベンダーから、別の形式のリンクが届くことがあります。

https://<vendor>.hbportal.co/flow/<flowId>?hash=…&userId=…

このリンクではポータルにサインインしません。単一のアンケートが開き、HoneyBook が弱い認証と呼ぶフローごとの認証情報が、localStorage["HONEYBOOK_REACT_WEAK_AUTH_<flowId>"] に保存されます。use_flow_link で取得し、get_flow で読み取ってください。

2 種類の認証情報は意図的に分離されており、それぞれ別のファイルとストアに保存されます。

	ポータルセッション	フロー認証情報
取得ツール	use_magic_link	use_flow_link
リンク形式	/app/link/resolve/…	/flow/<flowId>?hash=…
保存先	~/.honeybook-mcp/sessions.json	~/.honeybook-mcp/flows.json
読み取り可能なもの	ワークスペース、ファイル、請求書、支払い方法	そのアンケートのみ

各ツールは、相手側のリンク形式が渡された場合、名前を示して拒否します。また、ポータル用ツールにフロー認証情報だけを使って実行するよう求めると、後で意味の不明瞭な HoneyBook エラーが発生するのではなく、その旨を伝えます。list_active_sessions は両方の種類を個別に報告します。

get_flow は、アンケートページと同じ 2 つの呼び出しを行います。ベンダーの会社 ID を取得するための公開 GET /api/v2/flow/<flowId>/minimal、続いて GET /api/v2/client/flow/<flowId>/active?ctxc=<companyId> です。最初の呼び出しで会社 ID が返されない場合はそこで停止し、その旨を伝えます。ctxc なしで /active を呼び出すと、認証情報の期限切れのように見える単純な 400 が返されるためです。

注意点が 1 つあります。ストレージキーにはフロー ID が含まれるため、新しいアンケートを開くたびに、宣言済みの fetchproxy スコープに新しいキーが追加されます。拡張機能はペアリング時に承認したスコープに基づいて制限するため、アンケートごとに 1 回、再承認を求めます。これは拡張機能の正常な動作であり、不具合ではありません。

利用可能なツール

ベンダーにアクセスするツールでは、任意の origin 引数を指定できます（例：https://acme.hbportal.co）。アクティブなセッションが 1 つだけの場合は、自動的にそれが使用されます。

ツール	機能	権限
use_magic_link	マジックリンク URL からセッションを取得します	確認
list_active_sessions	種類ごとに分けてアクティブな認証情報を表示します	自動
use_flow_link	アンケート（フロー）の認証情報を取得します	確認
get_flow	1 件のアンケートとその回答を読み取ります	自動
list_workspace_files	ベンダーのファイルを種類で絞り込んで一覧表示します	自動
get_workspace_file	1 件のファイルの詳細をすべて取得します	自動
get_workspace	ワークスペースの詳細とステータスフラグを取得します	自動
list_payment_methods	保存済みの支払い方法（ブランド、末尾 4 桁、有効期限）を表示します	自動
sign_contract	ポータルで署名するためのディープリンクを取得します（確認後）	確認
pay_invoice	ポータルで支払うためのディープリンクを取得します（確認後）	確認
list_projects	ベンダーとのプロジェクトとそのワークスペース ID を一覧表示します	自動
get_project	プロジェクトの詳細（日付、場所、関係者、カスタムフィールド）を取得します	自動
list_messages	ワークスペース内のメッセージ（またはアクティビティログ）を新しい順に表示します	自動
get_message	1 件のメッセージの全内容（本文、添付ファイル、配信状況）を取得します	自動
send_message	ポータルから送信または返信します（確認後）	確認
mark_messages_seen	フィード項目を既読にします（読み取り操作だけでは既読になりません）	自動
list_meetings	予定されたミーティングと参加リンクを表示します。最も新しい日時が優先されます	自動
list_tasks	ベンダーから割り当てられたタスクと件数を表示します	自動
list_notes	ベンダーが共有したメモを表示します	自動
list_attachments	ワークスペース内の単独の画像、ファイル、ブックマークを一覧表示します	自動
list_payments	支払い済み・未払いの合計を含む支払いスケジュールを表示します	自動

send_message は、あなたに代わって操作する唯一のツールです。ポータルのアクティビティ作成画面と同じ send_workspace_message ジョブを作成し、HoneyBook の処理が完了するまで待機するため、ベンダーには通常の HoneyBook メールが届きます。確認するまでは、宛先、件名、本文のプレビューのみを表示します。詳しくは確認をご覧ください。

確認

sign_contract、pay_invoice、send_message は、実行前に確認を求めます。MCP の確認プロンプトを表示できるクライアント（Claude Code）では、確認プロンプトが表示されます。表示できないクライアント（claude.ai、Claude Desktop）では、最初の呼び出しは何も実行せず、プレビューと confirmToken を返します。同じ引数とそのトークンを使って再度呼び出すと、処理が進みます。トークンは一度だけ有効で、2 回の呼び出しの間にトークンが対象とする内容（ファイルのタイトル、メッセージ本文、ワークスペースの宛先）に変更があった場合は拒否されます。

variable	default
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	random per process	署名キーです。サーバーを再起動してもトークンを有効にしておく必要がある場合にのみ設定してください。

トラブルシューティング

• "HoneyBook auth expired" — Chrome でベンダーのマジックリンクを開き直し、use_magic_link を再実行してください。
• "No active HoneyBook session" — 先に use_magic_link を呼び出してください。
• "No active HoneyBook portal session. N flow (questionnaire) credentials are active" — /flow/ リンクを取得しましたが、呼び出したツールにはクライアントポータルのリンクが必要です。/app/link/resolve/… リンクを指定して use_magic_link を実行するか、get_flow を使ってアンケートを読み取ってください。
• "that is a questionnaire (flow) link, not a client-portal link" — このリンクには use_flow_link を使ってください。
• "no auth hash for flow …" — 渡したリンクから ?hash= パラメーターが失われています（ページの読み込み後に URL が書き換えられます）。ベンダーのメールから元のリンクをコピーし直してください。
• get_flow での "HoneyBook error 400 … NOT an auth failure" — 必須の入力値が不足しています。認証情報の問題ではありません。多くの場合、固定されている HONEYBOOK_API_VERSION が古くなっています。これを解除して、/api/gon から最新の値を読み取るようにしてください。use_flow_link を再実行しても解決しません。
• "no context id for flow …" — HoneyBook の公開 /minimal ルートが、アンケートの読み取りに必要なベンダーの会社 ID を返しませんでした。これも認証情報の問題ではありません。
• "fetchproxy capture failed" — ContextMint Bridge をインストールし、そのブラウザーでベンダーのマジックリンクを開いてください。
• "fetchproxy capture timed out" — 拡張機能が、読み取り可能なログイン済みポータルタブを見つけられませんでした。ベンダーのマジックリンクを開き、ポータルページが読み込まれたことを確認してから、再試行してください。
• "no confirmed browser session" — 拡張機能には接続されていますが、この MCP はまだ承認されていません。ContextMint Bridge のポップアップを開き、表示されたペアコードを承認してから、再試行してください。
• "this browser … cannot serve the … capability" — ペアリングしたブラウザーには、キャプチャに必要な API がありません。MCP やペアリングに問題はありません。再試行や再承認をしても解決しないため、必要な API を提供するブラウザー（たとえば Chrome）で実行してください。
• "localStorage keys not in declared set" — MCP が、既存のペアリングでは対象外のストレージキーを読み取ろうとしています。0.4.4 以前からのアップグレードを参照してください。再試行しても解決しません。また、バージョンの問題でもありません。

0.4.4 以前からのアップグレード

0.4.5 では、ブラウザー拡張機能で一度だけ再承認が必要です。 HoneyBook は、クライアントポータルのセッションを localStorage["jStorage"] から localStorage["HONEYBOOK_REACT_CURR_USER"] に移動したため、0.4.5 では別のストレージキーを読み取ります。拡張機能はペアリング時に MCP が宣言したスコープを承認するため、既存のペアリングでは新しいキーが対象にならず、次のエラーが表示されて、すべてのキャプチャが拒否されます。

localStorage keys not in declared set: HONEYBOOK_REACT_CURR_USER

解決するには、次の操作を一度だけ行います。

1. ContextMint Bridge 拡張機能のポップアップを開きます。
2. honeybook-mcp を取り消します。
3. use_magic_link を再実行します。新しいペアコードが表示されます。
4. ポップアップで承認します。これにより、新しいスコープを承認します。

それ以外に変更はありません。~/.honeybook-mcp/sessions.json に保存されている既存のセッションは引き続き使用でき、セッション自体の有効期限が切れている場合にのみ、再キャプチャが必要です。

セキュリティ

• セッションはローカルでキャプチャされます。認証トークンがマシンの外部に送信されることはありません。
• ~/.honeybook-mcp/sessions.json はモード 0600 で書き込まれ、ディレクトリはモード 0700 で書き込まれます。
• 書き込みツール（sign_contract、pay_invoice、send_message）の実行前には確認が求められます（確認を参照）。sign_contract と pay_invoice は、ヘッドレスで署名や支払いを行うのではなく、ポータルのディープリンクを返します。

開発

npm test        # run tests
npm run build   # tsc + esbuild bundle

ライセンス

MIT