freehire

freehire MCP サーバー

freehire の求人 API を利用する MCP サーバーです。Claude Desktop、Claude Code、互換性のあるエージェントなど、あらゆる MCP ホストから、個人用 API キーで認証して、ブラウザーを使わずに IT 求人を検索、絞り込み、応募できます。求人情報は企業の採用ページから直接収集されています。294K 社にわたる 3.3M 件以上の募集中ポジションを、単一のスキーマに正規化し、技術スタック、経験レベル、地域、勤務形態のタグを付けています（最新の数値）。

freehire CLI と同じ API、同じ認証情報を使い、シェルコマンドではなく MCP ツールとして提供します。

インストール

ホスト型エンドポイント（インストール不要、キー不要）

読み取り専用の求人検索ツールは、https://freehire.me/api/v1/mcp（Streamable HTTP）でもリモート提供されています。Claude Code では、プラグインとしてインストールします。

/plugin install freehire --marketplace strelov1/freehire-mcp

その他のホストでは、この URL をカスタムリモートコネクターとして追加します。

ローカルサーバー（npm）

グローバルインストールは不要です。ホストが npx 経由で実行します。ホストの MCP 設定に追加してください（Claude Desktop → Settings → Developer → Edit config、または Claude Code の場合は ~/.claude.json）。

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

Web アプリ（freehire.me → アカウントメニュー → API keys）で fhk_… キーを作成してください。すでに freehire CLI（freehire auth login）を使っている場合は、env を省略できます。サーバーは同じ ~/.freehire/creds.json を読み込みます。

認証

トークンと API のベース URL は、環境変数 → ~/.freehire/creds.json → デフォルトの https://freehire.me の優先順位で解決されます。

項目	参照元
トークン	FREEHIRE_TOKEN → 認証情報ファイル
API ベース URL	FREEHIRE_API_URL → 認証情報ファイル → https://freehire.me

サーバーは認証情報ファイルを読み込むだけで、書き込みは行いません（ログインは CLI の役割です）。トークンが設定されていない場合、サーバーの起動に失敗するのではなく、「未認証」という明確なエラーをツールから返します。

ツール

ツール	目的
whoami	認証済みユーザー（キーの確認）。
facets	フィルター／スキルの語彙：各ファセットの現在の値と件数。最初に呼び出してください。
search	キーワードとファセットによる求人検索。全文がMarkdown形式の求人情報と一致総数を返します。
market_fit	スキル一覧を現在の市場ニーズに照らして評価します（網羅状況と不足分）。
job	スラッグを指定して、1件の求人情報全文を取得します。
company	スラッグを指定して、企業情報と募集中の求人を取得します。
apply	求人への応募済みとして記録します。
save / unsave	ブックマークを追加／削除します。
stage	応募ステージを設定します（サーバー側で検証されます）。
note	自由記述のメモを追加します。
my	呼び出し元が管理している求人（すべて／閲覧済み／保存済み／応募済み）を、ステージとメモとともに取得します。
cv_tailor	求人に合わせた調整を開始（または再開）します。他の cv_* ツールで使用する CV ID を返します。
cv_list	呼び出し元が作成した、対象求人ごとの調整済み CV を取得します。
cv_context	調整済み CV で焦点を当て直すべき適合性分析を取得します（missing_have と missing_gap）。
cv_get	調整済み CV の全文書を取得します。
cv_edit	パスで指定した編集をまとめて調整済み CV に適用します。処理はアトミックで、サーバー側で検証されます（出典のない主張は拒否されます）。
cv_render	調整済み CV を PDF に変換し、base64 エンコードされた application/pdf リソースとして返します。
experience_list	候補者の経験バンクを、各実績の出所とともに取得します。cv_edit の evidence_id はここから取得します。
experience_add_employment / experience_add_achievement	勤務先、またはエビデンスを1件記録します。
experience_update_employment / experience_update_achievement	1件を修正します。フィールド単位で、指定しなかった項目は保持されます。
experience_remove_employment / experience_remove_achievement	1件削除します。取り消しはできません。勤務先を削除するには、先に空にする必要があります。
submit	求人をモデレーションに提出します。
my_submissions	呼び出し元が提出した求人とそのステータスを取得します。
jobs_add / jobs_edit	モデレーター：求人を作成／編集します（モデレーター権限がない場合は403）。
submissions_pending	モデレーター：審査待ちキューを取得します。
submission_approve / submission_reject	モデレーター：提出を承認／却下します。

フィルター。 search、market_fit、facets は同じ市場フィルターパラメーターを共有します：remote、region、country、city、company、category、role、seniority、employment_type、english_level、exclude_skill、salary_min、visa に加え、語彙内のその他のファセットを指定できる汎用の facets マップ（{"source": "greenhouse"}）。有効な値は facets ツールで確認してください。値を推測して指定しないでください。search では skills はフィルターですが、market_fit では評価対象のスキルセットです。

地理条件の範囲は広がります。 region、country、city は1つの OR グループです。region: ["eu"] と country: ["IT"] を指定すると、「ヨーロッパまたはイタリア」となり、地域だけを指定した場合と同じ結果をすべて返します。単一の国を検索するには、country を指定し、region は省略してください。この3つは「どこ」という1つの概念を表すため、場所を2つ選ぶと「いずれか」という意味になります。そのため、region: ["eu"] と country: ["BR"] の指定は「ヨーロッパまたはブラジル」となり便利です。AND に切り替える方法はありません。_mode=and は地理条件には適用されません。

認識されないパラメーターは拒否されず、無視されます。 API が認識しないフィルターキーを指定してもリクエストは失敗せず、検索範囲が広がります。このようなキーは結果の ignored リストに返され、文法上の単複だけが誤っている場合は did_you_mean も返されます。search では total とともに報告されます。facets と market_fit は単一のオブジェクトを返すため、その場合に限り {data, ignored} でラップされます。正常な呼び出しの形式は変更されません。ignored を含む結果の数値は、指定した条件より広い範囲についてのものです。報告する前に、提案された名前で再試行してください。

説明。 search は API のエージェントエンドポイントを読み込むため、すべての検索結果には投稿内容の全文がMarkdown形式で含まれます。ホストは、ヒットごとに job を呼び出さなくても、結果一式を確認できます。説明は長いため、limit は控えめに設定してください。 証拠のルール。 すべての実績には、誰が申告したかが記録されます。 cv_import、stated_in_chat、manual は候補者本人が申告したことを意味し、履歴書に引用できます。agent_inferred はモデルが読み取って記録したことを意味し、引用できません。cv_edit は、引用可能な実績を指す evidence_id がない限り、候補者に関する記述を拒否します。そのため、experience_list は cv_edit を使えるようにするツールです。

実績を修正しても、このラベルは変わりません。agent_inferred の実績は、どのように言い換えても引用できません。引用可能にするには、候補者に尋ねて、本人の発言を experience_add_achievement で記録する必要があります。

削除は取り消せません — 銀行に元に戻す機能はありません。場所を削除すると、その下にあるすべての実績も削除されるため、場所を削除する前に中身を空にする必要があります。2つの実績を1つにまとめ、両方の数値を残すことはサイト上で可能です。

各ツールは、API の生の data を JSON テキストで返します。API エラーは HTTP ステータスを含む isError 結果になり、401 の場合は認証に関するヒントも追加されます。

開発

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

ライセンス

MIT — LICENSE を参照してください。freehire のバックエンドと CLI も MIT です。