Juicebox MCP

Juicebox のソーシングデータを Claude に読み込むローカル MCP サーバー — 保存済み検索とそのスコアリング結果を、ログイン済みの自分の Juicebox セッションを使って読み取ります。

完全に自分のマシン上で動作します。セッションが外部に出ることはなく、すべての呼び出しは自分自身として、自分のシート上で実行されます。

読み取りはエクスポートクレジットを消費しません。 読み取りツールが返すものはすべて、検索結果ページがすでに描画しているのと同じ無料のサーフェスから取得されます。書き込みを行うツールは 1 つだけで、その旨が明記されています: jb_run_search はワークスペースに実際の保存済み検索を作成します。

インストール

オプション A — デスクトップ拡張機能（最も簡単）

Releases から juicebox-mcp.mcpb をダウンロードし、ダブルクリックするか、Claude Desktop → 設定 → 拡張機能 にドラッグ＆ドロップします。

貼り付ける API キーはありません。インストール後、以下の一度だけのブラウザ手順を実行してください。

オプション B — ソースから

git clone https://github.com/jnot807/juicebox-mcp.git
cd juicebox-mcp
npm install          # also downloads the Chromium build (see note)
npm run login        # a real browser opens — sign in to Juicebox yourself
npm run check        # proves the session works headless

次に Claude Code に登録します:

claude mcp add -s user juicebox -- node "$(pwd)/server.js"

-s user を付けるとすべてのセッションで利用可能になります。付けない場合、登録は実行したディレクトリに限定されます。

一度だけのブラウザダウンロード

これは実際の Chromium を駆動するもので、そのバイナリは node_modules の一部ではありません — 共有キャッシュ（macOS では ~/Library/Caches/ms-playwright）への約 500MB の一度きりのダウンロードです。

npm install は postinstall ステップで自動的に取得します。デスクトップ拡張機能のユーザーは手動で一度実行する必要があります。拡張機能には node_modules は同梱されますが、そのキャッシュは同梱されないためです:

npx patchright install chromium

これがない場合、サーバーは実行ファイルが見つからないというスタックトレースを投げるのではなく、平易な言葉でその旨を伝えます。

サインイン

認証はキーではなく、実際のサインインです。npm run login でブラウザウィンドウが開きます。通常どおり Juicebox にサインインしてください。セッションはその後 session/（gitignore 済み、chmod 600）に保存され、ヘッドレスで再利用されます。

npm run check が失敗し始めたら、再度サインインしてください — セッションは期限切れになります。

ツール

experience[] は過去の雇用主を見る唯一の方法です。API ペイロードは現在のものしか保持しないため、対象企業の出身者はこれなしでは見えません。

デフォルトで読み取るプロジェクト

ハードコードされたものはありません。サインイン時にプローブが /projects を読み込み、これは自分のシートが見えるプロジェクトへリダイレクトされ、その id が session/session-meta.json の defaultProjectId として保存されます。

これは一度だけ書き込まれ、その後は放置されます。リダイレクトはアプリが最後に開いていたプロジェクトに従うため、毎回それを信頼すると、projectId なしのツール呼び出しが昨日とは異なるプロジェクトを読むことになります。

解決順序:

1. JUICEBOX_PROJECT_ID（環境変数 — デスクトップ拡張機能のオプションの「デフォルトプロジェクト」フィールドが設定するもの）

2. JUICEBOX_VALIDATOR_PROJECT（環境変数 — 認証チェックもそのプロジェクトに固定します）

3. session/session-meta.json の defaultProjectId（ディスカバリーで設定）

すべてのツールは明示的な projectId も受け取り、これが常に優先されます。

Juicebox のプロジェクト id は c5PheL2fANnX6uBQVUdo のような約 20 文字のキーです — URL の /project/<id>/ の部分です。UUID を渡すと、存在しないプロジェクトへ黙って移動するのではなく、説明付きでサーバーが拒否します。

ツールが備える 2 つのルール

• verdictFound: false → unknown、決して否定ではありません。 「証拠が見つからない」と「証拠がノーと言っている」は異なる判定です。これらを同一視すると、実際には誰も確認できなかった基準で候補のスコアが下がります。

• 広いスキル用語はランキングを薄めます。 スキルは OR 重み付けです。カスタマーサクセス検索での「Account Management」のような人口全体にわたる用語は、プールを約 3.4 倍に膨らませます。一般的な用語を落とし、1 つの必須要件をスキルフィルターに昇格させてください。

サーバー稼働中にスクリプトを実行する

ブラウザプロファイルを共有することはできません: session/profile/ は単一書き込み者であり、MCP サーバーは稼働中は常にそれを保持します。それを開こうとする 2 番目のプロセスは認証チェックに失敗します — これは「セッション期限切れ」として報告され、再ログインを繰り返す堂々巡りに陥ります。

診断には、チェックポイントから新しいコンテキストを構築してください。ロックなし、同じセッション:

const { chromium } = require('patchright');
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({ storageState: 'session/storage-state.json' });

仕組みと落とし穴

結果ページは初回読み込み時にサーバーサイドレンダリングされるため、/api/profiles/results は操作時にのみ発火します。クライアントはページャーを微調整してアプリ自身にリクエストを発行させ、その後レスポンスをキャプチャします — これには表示中のページだけでなく、ランク付けされたセット全体が含まれます。

client.js を編集する人を噛むであろう 3 つの点:

1. addInitScript は絶対に使わないでください。 Patchright は検出対策としてこれを黙って no-op にします — エラーもなく、スクリプトが実行されないだけです。page.on('response') を使用してください。

2. API の linkedin_url は暗号化されています（hex:hex）、profiles[].url と profileDetails.id も同様です。実際の URL は描画されたカードから取得され、正規化された full_name で結合されます — ライブ検索で 100% と測定されています。

3. ページネーション途中でリストが空白になります。 null のページャー読み取りは「まだ移動中」を意味し、「失敗」ではありません。遷移中にページャー変更検出に何かをゲートすることは、以前の 2 つのバグの原因です。

壊れたとき

これは Juicebox の内部 API に依存しています。安定性の契約はなく、予告なく変更される可能性があります。

• npm run check が失敗 → セッション期限切れ: npm run login。

• サーバーが Chromium がないと言う → npx patchright install chromium。

• jb_get_results が source: "dom-fallback" を返す → API キャプチャが壊れました。matchRate と基準が失われます。RESULTS_PATH がまだ一致するか確認してください。

• jb_get_results が joinedLinkedInUrls: 0 を報告する → カードのマークアップが変更されました。harvestCards / rewindToFirstPage を見直してください。

• 検索リストが空 → プロジェクトページのマークアップが変更されました。listSavedSearches を参照してください。

要件

• Node.js 18 以降

• サインインできる Juicebox アカウント

• Chromium ダウンロード用に約 500MB の空きディスク

ライセンス

MIT。Juicebox とは提携しておらず、Juicebox による承認も受けていません。