MCP FactorialHR

MCP FactorialHR

FactorialHR 向けの決定版 Model Context Protocol サーバー

Claude のような AI アシスタントから FactorialHR に完全にアクセスできる、包括的な Model Context Protocol（MCP）サーバーです。従業員、チーム、休暇、プロジェクト、研修、採用などを、組み込みの安全ガードレールとともに管理できます。

この MCP サーバーを選ぶ理由

• コンテキスト最適化：14 個の階層型ツール（117 の操作）により、個別のツールと比べてコンテキスト使用量を 88％ 削減
• 完全な CRUD 操作：すべての主要なエンティティで作成、読み取り、更新、削除が可能
• 安全ガードレール：リスクの高い操作には明示的な確認が必要
• 監査ログ：デバッグ用に、すべての書き込み操作がタイムスタンプとコンテキストとともに記録されます
• エンタープライズ対応：適切な管理体制のもとで AI を連携する必要がある企業向けに構築されています

機能

階層型ツールの検出（v8.0.0+）

MCP サーバーでは、コンテキストを最適に利用するために階層型のツール構造を使用しています。124 個の個別ツールの代わりに、action パラメーターを使用する 14 個のカテゴリ別ツールを利用できます。

ツール	説明	アクション
factorial_discover	利用可能なカテゴリを検出します	-
factorial_employees	従業員管理	list, get, search, create, update, terminate
factorial_teams	チーム管理	list, get, create, update, delete
factorial_locations	拠点管理	list, get, create, update, delete
factorial_contracts	契約／給与データ	list, get_with_employee, by_job_role, by_job_level
factorial_time_off	休暇管理	10 個のアクション
factorial_attendance	シフトと勤怠記録	clock_in、audit、log_range を含む 14 個のアクション
factorial_documents	ドキュメント管理	8 個のアクション（ダウンロードには OAuth2 が必要です。下記を参照）
factorial_job_catalog	職種／職位	list_roles, get_role, list_levels
factorial_projects	プロジェクト管理	プロジェクト、タスク、作業者、時間に関する 16 個のアクション
factorial_training	研修管理	研修、セッション、登録に関する 12 個のアクション
factorial_work_areas	作業エリア管理	list, get, create, update, archive, unarchive
factorial_ats	応募者追跡	採用に関する 17 個のアクション
factorial_payroll	給与データ（読み取り専用）	6 個のアクション

使用例：

// List all employees
factorial_employees({ action: 'list', page: 1, limit: 50 });

// Get a specific employee
factorial_employees({ action: 'get', id: 123 });

// Search employees
factorial_employees({ action: 'search', query: 'john' });

// Create a leave request
factorial_time_off({
  action: 'create',
  employee_id: 123,
  leave_type_id: 1,
  start_on: '2026-02-01',
  finish_on: '2026-02-05',
});

// Discover available actions for a category
factorial_discover({ category: 'employees' });

14 カテゴリーにわたる 124 の操作

カテゴリー	操作
従業員	list, get, search, create, update, terminate
チーム	list, get, create, update, delete
勤務地	list, get, create, update, delete
休暇	list_leaves, get_leave, list_types, get_type, list_allowances, create, update, cancel, approve, reject
勤怠	list, get, create, update, delete, clock_in, clock_out, status, gaps, audit, log_range, log_days, list_edit_requests, create_edit_request
プロジェクト	プロジェクト、タスク、作業者、時間記録に関する 16 の操作
トレーニング	トレーニング、セッション、登録に関する 12 の操作
作業エリア	list, get, create, update, archive, unarchive
ATS	求人情報、候補者、応募、採用ステージに関する 17 の操作
給与計算	補足情報、納税者識別情報、家族状況の一覧取得／取得（読み取り専用）
ドキュメント	フォルダー、ドキュメント、ダウンロードに関する 8 つの操作（⚠️ ダウンロードには OAuth2 が必要です）
職種カタログ	list_roles, get_role, list_levels（読み取り専用）
契約	list, get_with_employee, by_job_role, by_job_level（読み取り専用）

勤怠と Registro Horario

Factorial では、従業員は日ごとに勤務時間を記録します。factorial_attendance を使うと、Claude は 1 日分または 1 か月分の勤務時間を、API キーからアクセスできる任意の従業員について記録できます。

時刻は会社の現地時間での HH:MM 形式で、Factorial に表示される時刻と完全に同じです。Factorial は会社のタイムゾーンに基づいて時刻を適用し、サーバーがタイムゾーン間で変換することはありません。このサーバーによって書き込まれた記録には source: "api" が設定されるため、Factorial 独自のアクティビティログにある実際の打刻と区別できます。

書き込み時に指定する勤務時間（date、clock_in、clock_out）は、入力メタデータとは別のものです。Factorial は、記録がいつ、どのように入力されたかを示す created_at、updated_at、in_source／out_source を設定します。これらは API 経由で設定または変更できません。各 create、update、clock_in、clock_out と、すべての一括プレビューおよび結果には、指定した勤務時間が記載され、この点についての説明も一度記載されます。

アクション	説明
status	従業員が出勤中かどうか、および出勤してからの経過時間を示します。常に設定済みの ID を表示します。
clock_in、clock_out	現在時刻で出退勤を記録します。または、date と time（会社の現地時刻で HH:MM）を指定して、打刻を忘れた場合の時刻を申告できます。未来の時刻を申告した場合、リクエストを送信する前に拒否されます。未終了の勤務がない場合、または申告時刻が勤務開始時刻より前の場合、申告による clock_out は拒否されます。
gaps	契約上の所定労働時間が記録済みの時間を上回る、期間内の勤務日を示します。週末、祝日、終日の休暇は除外されます。
audit	期間内の各暦日について、日種別、所定時間と記録時間、休暇の適用状況、記録されている勤務シフト、およびステータス（complete、missing、short、over、weekend、bank_holiday、on_leave、half_day_leave、no_contract_data、future）を1行ずつ表示します。missing は記録がない状態です。short は一部の時間が記録されているものの、許容範囲を超えて所定時間に達していない状態で、差分も表示されます。承認済みの日付は別途表示され、書き込みがロックされます。修正には create_edit_request を使用します。ヘッダーには、契約上の所定時間が適用される祝日と休暇を含む expected と、記録時間が実際に満たすべき workday expected が表示されます。statuses を指定すると、サマリーを特定のステータスに絞り込めます。format は summary（デフォルト。対応が必要な日付のみ）、table（すべての日付）、または json（台帳）です。打刻した時間と、本来の所定時間を照合する際の出発点になります。
log_range	日ごとのパターン（segments）を、期間内のすべての勤務可能日に適用します。週末、祝日、契約上の所定時間が0分の日、承認済みの休暇、未来の日付、承認済みの日付、exclude_dates、および既存の勤務シフトと重複するセグメントは除外されます。
log_days	他のプラットフォームから移行する際に、セグメントを含む日付の一覧を明示して書き込みます。未来の日付、承認済みの休暇、承認済みの日付、重複のみ拒否されるため、勤務した土曜日も記録できます。
list、get、create、update、delete	個別の勤務シフト記録を操作します。list では start_on と end_on（または ids、または updated_at）が必要です。Factorial はこのエンドポイントでページングを無視するため、ページングはクライアント側で行います。list の fields: "compact" を指定すると、より小さいペイロード（日付、clock_in、clock_out、分数、in_source）が返されます。get では完全なレコードが返されます。
list_edit_requests、create_edit_request	承認済みの日付に直接時間を書き込めないため、その日付を修正する Factorial のエンドポイントです。リクエストを送信すると、タイムシートの承認者に通知されます。そのため、設定済みの ID であっても create_edit_request はプレビュー表示され、トークンが必要です。

// Find the missing days first
factorial_attendance({ action: 'gaps', start_on: '2026-03-01', end_on: '2026-03-31' });

// Preview a month of split days; nothing is written yet
factorial_attendance({
  action: 'log_range',
  start_on: '2026-03-01',
  end_on: '2026-03-31',
  segments: [
    { clock_in: '09:00', clock_out: '14:00' },
    { clock_in: '15:00', clock_out: '18:00' },
  ],
});
// -> "Plan for <name> (<id>) ... 20 days to write, 40 shift records, 160h ... confirmation_token: <token>"

// Same call plus the token writes it
factorial_attendance({ action: 'log_range', /* same arguments */ confirmation_token: '<token>' });

// Afterwards, reconcile the month
factorial_attendance({ action: 'audit', start_on: '2026-03-01', end_on: '2026-03-31' });

未来の日付ルールにおける「今日」は、サーバーを実行しているマシンのタイムゾーンの日付です。そのため、会社のタイムゾーンで実行するか、境界日が1日ずれる可能性を受け入れてください。祝日は、Factorial の会社独自のカレンダー（worked_times.day_type）から取得するため、祝日リストは不要です。承認済みの休暇は timeoff/leaves から読み取ります。情報源となるシステムのほうが正しく、Factorial の休暇記録が古い場合は、skip_leave: false を渡してください。半日休暇の日は log_range の対象外となり、プレビューに表示されます。半日分の勤務時間を記録するには log_days を使用してください。

毎日きっかり09:00に出勤する人はいません。また、1か月分が同じ時刻の記録ばかりというのは、実際の registro では見られないパターンです。log_range または log_days に jitter_minutes（5～10が妥当です）を渡すと、記録する各時刻が、その日の範囲内で指定したパターンから最大でその分数だけ変動します。各時間帯が互いに重なることはありません。別の種類の変動には variation_minutes を渡してください。これは1日全体に決定論的なオフセットを加え、開始時刻が日ごとにずれるようにします。jitter_minutes は1日の時間帯内だけで変動するため、このような変動は生み出せません。どちらも従業員、日付、および（ジッターの場合は）時間帯から導出されるため、プレビューには書き込まれる正確な時刻が表示され、確認トークンはその時刻に紐付けられ、再試行時には以前に作成した記録を識別できます。記録には引き続き source: "api" が付与されます。これらのオプションは再構築した勤務時間を現実的にするものであり、記録の出所を偽るものではありません。

すべての gaps、audit、一括書き込みのプレビューには、最初に Data read の行が表示されます。対象期間のうち、契約データがある日数と、読み取られた休暇およびシフトの記録数です。読み取りでは Factorial のページネーションを最後までたどるため、どの長さの期間でもデータがそろいます。API から何も返されなかった日付は no_contract_data として報告され、勤務できない日として扱われて書き込みの対象にはなりません。こうした日付は通常、雇用開始日前の日付です。そうでない場合は、読み取りが不完全であり、結果を信頼すべきではありません。

承認済み期間。 Factorial で日付のタイムシートが確認済みになると、その日は書き込み不可となり、シフトの書き込みは403で拒否されます。audit は他の情報とあわせて attendance/reviews を読み取り、書き込み前に該当日を承認済みとしてマークします。log_range と log_days は、週末や承認済みの休暇日と同様に、その日をスキップします。承認済みの日を修正するには create_edit_request を使用します。タイムシートの承認者が判断する申請を提出できます。提出済みの申請は list_edit_requests で読み取れます。申請の提出は、人に通知されるため、設定済みの本人であってもプレビューとトークンによる確認が必要です。

2026-02-30 のような存在しない日付は、次の有効な日付へ暗黙的に繰り越されることなく拒否されます。2024-02-29 のような実在するうるう日は通常どおり受け付けられます。

月次監査。 まず対象期間に対して audit を実行してください。tolerance_minutes（デフォルトは15分）の範囲内であれば、期待される合計時間に対する差は complete として扱われるため、現実的な出退勤時刻やジッターを加えた過去データの記録が不足として表示されることはありません。台帳と、手元で把握している情報（カレンダー、別の勤怠管理システム、祝日に実際に勤務した日など）を照合し、差異を修正してください。不足日は log_range または log_days、誤った記録は delete または update で修正し、その後もう一度 audit を実行して、すべての勤務日が complete と表示されることを確認します。

これらのワークフローをユーザー向けにまとめたプロンプトが5つあり、モデル向けにそれらを説明するガイドリソースもあります。5 MCP Prompts と factorial://guides/registro-horario を参照してください。Claude Code を含む一部のクライアントでは、プロンプトは人間が実行するスラッシュコマンドとしてのみ表示され、モデル自身が読み取る方法がありません。そのため、各プロンプトの手順は factorial://prompts/<name> のリソースとしても公開されています。 employee_idを省略できるように、FACTORIAL_EMPLOYEE_IDを自分の従業員IDに設定してください。他の従業員を対象とする書き込みと、すべての一括書き込みには確認トークンが必要です。詳細は安全性とセキュリティを参照してください。

6 MCP リソース

リソース URI	説明
factorial://org-chart	組織階層の全体図（Markdown）
factorial://guides/registro-horario	このサーバーでregistro horarioを監査、記入、管理する方法（Markdown）
factorial://employees/directory	チーム別の従業員ディレクトリ（Markdown）
factorial://locations/directory	従業員数を含む拠点ディレクトリ（Markdown）
factorial://timeoff/policies	すべての休暇タイプとポリシー（JSON）
factorial://teams/{team_id}	メンバー一覧を含むチームの詳細（JSON、テンプレート形式）
factorial://prompts/{name}	勤怠プロンプトの手順テキスト。実行せずに読み取れます（Markdown）

5 MCP プロンプト

プロンプトはユーザーが呼び出す手順です（Claude Codeでは/mcp__factorial__<name>というスラッシュコマンドとして表示されます）。勤怠プロンプトは、手順の開始時に必要なデータを事前に読み込み、後続のツール呼び出しを正確に示すため、小規模なモデルでもワークフローを実行できます。プロンプト自体が何かを書き込むことはありません。書き込みはfactorial_attendanceとその確認ゲートを通じて行われます。

プロンプト	引数	動作
attendance_audit	start_on、end_on、employee_id（すべて省略可能）	監査を実行し（デフォルト：今月の初日から今日まで、FACTORIAL_EMPLOYEE_ID）、読み取り専用レポートを求めます。月ごとの予定時間と記録時間の比較、不足日数と超過日数、データカバレッジに関する警告を報告します。
attendance_fill	segments（必須）、start_on、end_on、employee_id、observations、jitter_minutes	空き時間を読み取り、解析したパターンで正確な log_range 呼び出しを引き渡し、その後、プレビュー、人による確認、トークン、再試行、検証の手順を案内します。segments は "09:00-14:00, 15:00-18:00" です。
attendance_today	segments（必須）、employee_id、observations、jitter_minutes	今日の状況を読み取り、対応を判断します。週末、祝日、休暇中、勤務時間が未確定、または勤務記録が完了している場合は何もせず、それ以外の場合は今日の log_days を、設定された ID に限り同じセッション内で確認してから実行します。
attendance_reconcile	known_absences（必須）、start_on、end_on、employee_id	監査を実行し、申告された既知の不在日リスト（休日、病欠、出張）と食い違う日のみを報告します。読み取り専用です。
attendance_fill_days	days（必須）、employee_id、observations、jitter_minutes	日ごとに異なるパターンを指定した明示的な日付のリストについて、registro horario を 1 回の log_days 呼び出しで入力します。プレビュー、人による確認、トークン、再試行、検証を行います。days は [{"date":"2026-03-02","segments":"09:00-14:00, 15:00-18:00"}] です。
summarize_team	team_id	メンバーと役割を含むチームの概要です。
time_off_report	employee_id	従業員の休暇レポートです。休暇日数と最近の休暇を確認できます。

毎日の記録をスケジュールに従って実行する。 MCP にはスケジューラーがないため、スケジュールはクライアント側で設定します。Claude Code では、/schedule で attendance_today を指定したパターンで呼び出すルーチンを作成でき、/loop でセッションが開いている間、それを繰り返し実行できます。任意の cron から、プロンプトを入力として claude -p を実行することもできます。このプロンプトが記録を行うのは、今日が勤務日で、勤務時間がまだ記録されていない場合のみです。また、対象は FACTORIAL_EMPLOYEE_ID の従業員に限られ、いずれの場合も 1 行で報告します。生成される記録は労働時間の法的文書です。そのため、スケジュールに設定するパターンには実際に働く時間を指定してください。勤務しない日は、休暇の記録を作成するか、手動で修正する必要があります。

アーキテクチャの特徴

• 安全ガードレール：終了や削除などの高リスク操作には確認を設定
• 監査ログ：すべての書き込み操作を、タイムスタンプとコンテキストを含めてプロセス内に記録
• キャッシュ：メモリ内の TTL ベースのキャッシュ（リソースの種類ごとに設定可能）
• ページネーション：すべての一覧表示操作でページネーションに対応
• 再試行ロジック：レート制限への対応を含む指数バックオフ
• 検証：Zod スキーマによるランタイム検証

クイックスタート

1. MCP 設定に追加

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"]
    }
  }
}

2. API キーを設定

プロジェクトのルートディレクトリに .env ファイルを作成します。

FACTORIAL_API_KEY=your-api-key-here

または、MCP 設定に直接渡します。

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 使い始めましょう！

設定が完了したら、Claude に次のように尋ねてみてください。

• 「エンジニアリングチームのメンバーは誰ですか？」
• 「John Smith を新しい従業員として作成して」
• 「従業員 42 の保留中の休暇申請を承認して」
• 「Q1 Marketing Campaign という新しいプロジェクトを作成して」
• 「Sarah を Leadership Training プログラムに登録して」
• 「募集中の求人をすべて表示して」
• 「Senior Developer の職種に応募した候補者は誰ですか？」

API キーの取得

この MCP サーバーを使用するには、FactorialHR API キーが必要です。取得方法は次のとおりです。

1. 管理者として FactorialHR にログインします
2. Settings → API keys に移動します
3. **「New API key」**ボタンをクリックします
4. キーにわかりやすい名前を付けます（例：「Claude Code」または「MCP Server」）
5. Create をクリックすると、API キーが表示されます
6. キーをすぐにコピーしてください。キーが表示されるのは一度だけで、後から取得することはできません
7. キーを .env ファイルまたは MCP 設定に追加します

重要：API キーは FactorialHR のデータに完全にアクセスでき、有効期限はありません。安全に保管し、バージョン管理にコミットしないでください。また、定期的にローテーションしてください。

OAuth2 の設定（ドキュメントのダウンロードに必須）

ドキュメントのダウンロード操作（download_payslips、download）には、OAuth2 認証が必要です。これは Factorial API の制限です。ダウンロードエンドポイントでは API キー認証を受け付けていません。

注：OAuth アプリケーションを作成するには、Factorial の管理者アクセス権が必要です。

ステップ 1：OAuth2 アプリケーションを作成

1. 次の URL に移動します：https://api.factorialhr.com/oauth/applications
2. **「New application」**をクリックします
3. 次の項目を入力します。
   • Redirect URI：http://localhost:8080/callback（またはアクセス可能な任意の URL）
   • Confidentiality：Yes（サーバーアプリケーション）
   • Scopes：必要なスコープを選択します。
     • ダウンロードに必須：Documents、Employees
     • MCP の全機能を利用するために推奨：Contracts、Payroll、Payroll supplements、Time off、Shift management、Trainings、Recruitment、Company locations、Job catalog
4. 保存し、Client ID と Client Secret を控えます

ステップ 2：認証コードを取得

ブラウザーで次の URL を開きます（YOUR_CLIENT_ID を置き換えてください）。

https://api.factorialhr.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&response_type=code

• ログインしてアプリを認可します
• コールバック URL に ?code=AUTHORIZATION_CODE が付いた状態でリダイレクトされます
• URL からコードをコピーします（有効期限が短いため、すぐにステップ 3 に進んでください）

ステップ 3：コードをトークンに交換

次の curl コマンドを実行します（プレースホルダーを置き換えてください）。

curl -X POST 'https://api.factorialhr.com/oauth/token' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'grant_type=authorization_code' \
  -d 'redirect_uri=http://localhost:8080/callback'

access_token と refresh_token を含むレスポンスが返されます。refresh_token を保存してください。

ステップ 4：MCP サーバーを設定

OAuth2 認証情報を MCP 設定に追加します。

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key",
        "FACTORIAL_OAUTH_CLIENT_ID": "your-client-id",
        "FACTORIAL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "FACTORIAL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

または .env ファイルに追加します。

FACTORIAL_API_KEY=your-api-key
FACTORIAL_OAUTH_CLIENT_ID=your-client-id
FACTORIAL_OAUTH_CLIENT_SECRET=your-client-secret
FACTORIAL_OAUTH_REFRESH_TOKEN=your-refresh-token

重要な注意事項

• リフレッシュトークンの有効期限は 1 週間です。期限が切れた場合は、ステップ 2～3 をやり直す必要があります
• MCP サーバーは、リフレッシュトークンを使用してアクセストークンを自動的に更新します
• ドキュメントのダウンロードが突然機能しなくなった場合は、リフレッシュトークンの有効期限が切れている可能性があります

ユースケース

マネージャー向け

• チーム構成を作成、管理する
• 休暇申請を承認または却下する
• 従業員をプロジェクトに割り当てる
• プロジェクトの作業時間記録を追跡する
• トレーニングの登録状況を監視する

人事担当者向け

• 新入社員のデータをすべて入力してオンボーディングする
• 求人情報と採用パイプラインを管理する
• 採用段階ごとに候補者の応募状況を追跡する
• 組織構造の分析を生成する
• 研修プログラムと受講登録を管理する

開発者向け

• 従業員のコンテキストが必要な AI ワークフローを構築する
• Claude とのカスタム連携を作成する
• AI アシスタンスを活用して人事プロセスを自動化する
• レポートと分析を生成する

設定オプション

環境変数	説明	デフォルト値
FACTORIAL_API_KEY	FactorialHR API キー	必須
FACTORIAL_API_VERSION	API バージョン	2026-07-01
FACTORIAL_EMPLOYEE_ID	従業員 ID：デフォルトの対象、および出退勤管理で認証なしに使用される ID	-
FACTORIAL_TIMEOUT_MS	リクエストのタイムアウト（ms）	30000
FACTORIAL_MAX_RETRIES	最大再試行回数	3
DEBUG	デバッグログを有効にする	false
FACTORIAL_OAUTH_CLIENT_ID	OAuth2 クライアント ID（ダウンロード用）	-
FACTORIAL_OAUTH_CLIENT_SECRET	OAuth2 クライアントシークレット（ダウンロード用）	-
FACTORIAL_OAUTH_REFRESH_TOKEN	OAuth2 リフレッシュトークン（ダウンロード用）	-

安全性とセキュリティ

確認が必要な操作

次の操作では明示的な確認（confirm: true）が必要です。確認なしで呼び出すと、ツールは影響を説明する警告を返し、変更は行いません。リスクは src/write-safety.ts で操作ごとに分類されています。以下の操作は、リスクが高または中と評価されているかどうかにかかわらず、すべて確認が必要です。

• factorial_employees({ action: 'terminate' }) - 従業員を退職させます
• factorial_teams({ action: 'delete' }) - チームを完全に削除します
• factorial_locations({ action: 'delete' }) - 場所を完全に削除します
• factorial_projects({ action: 'delete' }) - プロジェクトを完全に削除します
• factorial_projects({ action: 'delete_task' }) - プロジェクトのタスクを削除します
• factorial_projects({ action: 'delete_time' }) - 勤務時間の記録を削除します
• factorial_projects({ action: 'remove_worker' }) - 従業員のプロジェクトへの割り当てを削除します
• factorial_attendance({ action: 'delete' }) - シフトの記録を削除します
• factorial_time_off({ action: 'cancel' }) - 休暇申請をキャンセルします
• factorial_time_off({ action: 'reject' }) - 休暇申請を却下します
• factorial_training({ action: 'delete' }) - 研修プログラムとその受講登録を削除します
• factorial_training({ action: 'delete_session' }) - 研修セッションを削除します
• factorial_training({ action: 'unenroll' }) - 従業員の研修受講登録を削除します
• factorial_ats({ action: 'delete_posting' }) - 求人情報とその応募を削除します
• factorial_ats({ action: 'delete_candidate' }) - 候補者を完全に削除します
• factorial_ats({ action: 'delete_application' }) - 応募を完全に削除します

確認トークンで制御される操作

勤怠の書き込みは、対象者と変更するレコード数によって制御されます。この条件は、操作ごとのポリシーでは表現できません。最初の呼び出しでは何も書き込まず、対象者、日付、合計を示すプレビューと、15 分間有効でそのプランに厳密に紐付けられた confirmation_token を返します。トークンを付けて再度呼び出すと実行されます。その間にプランが変わった場合（誰かがシフトを書き込んだ場合）、トークンは拒否され、新しいプレビューが発行されます。最初の呼び出しでは渡すトークンが存在しないため、confirm: true でこの制御を回避することはできません。

対象者が設定済みの FACTORIAL_EMPLOYEE_ID と異なる場合、およびこの変数が未設定の場合は、常に制御されます。

• factorial_attendance({ action: 'create' }) - 別の人のシフトを作成します
• factorial_attendance({ action: 'update' }) - 別の人のシフトを更新します（対象者を確認するため、まずシフトを取得します）
• factorial_attendance({ action: 'delete' }) - 別の人のシフトを削除します。confirm: true も必要です
• factorial_attendance({ action: 'clock_in' }) - 別の人の出勤を記録します
• factorial_attendance({ action: 'clock_out' }) - 別の人の退勤を記録します

対象者に関係なく、件数自体がリスクとなるため、常に制御されます。

• factorial_attendance({ action: 'log_range' }) - 期間内の勤務可能日ごとに、1 件以上のシフトレコードを書き込みます
• factorial_attendance({ action: 'log_days' }) - 明示的に指定された日付のリストを書き込みます
• factorial_attendance({ action: 'create_edit_request' }) - 人に通知が送られるタイムシート変更リクエストを申請するため、設定済みの本人に対する操作でも制御されます

一括呼び出しが一部失敗した後に再実行しても、それ以前に自身が書き込んだ内容と重複しないよう安全に処理されます。プランナーは既存のシフトを再取得し、重複するものをスキップします。ただし、読み取りから書き込みまでの間に別の書き込みが行われた場合は防げません。

ドキュメントのダウンロード

ドキュメント名は呼び出し元ではなく Factorial のメタデータに由来するため、ダウンロード時には信頼できないものとして扱われます。

• 名前は単一のパスセグメントに変換されるため、パス区切り文字を含む名前で output_dir の外にダウンロード先を変更することはできません。
• 制御文字は削除され、長すぎる名前は拡張子を残して短縮されます。
• 既存のファイルが上書きされることはありません。 対象名がすでに使われている場合、ファイルは name (1).ext、name (2).ext のように保存されます。これにより、output_dir 内の既存ファイルが保護され、同じ名前の 2 つのドキュメントが 1 つにまとめられるのを防ぎます。

ダウンロードは指定された output_dir に書き込まれるため、ソースツリーやホームディレクトリではなく、ダウンロード用のディレクトリを指定してください。

読み取り専用のカテゴリー

一部のカテゴリーは、セキュリティ上の理由から意図的に読み取り専用になっています。

• 給与：手当、納税者識別番号、家族状況
• ドキュメント：フォルダーとドキュメントのメタデータ（給与明細とドキュメントにはダウンロードツールを利用できます）
• 契約：過去の契約データ

レスポンスの最適化

ドキュメントと契約の一覧操作は、トークンの上限超過を防ぐため、デフォルトで概要形式を返します。

ドキュメント（factorial_documents({ action: 'list' })）：

• 返される項目：id、name、folder_id、employee_id、mime_type（5 項目）
• デフォルトの上限：1 ページあたり 100 件のドキュメント
• 詳細を取得するには、factorial_documents({ action: 'get', id: X }) を使用してすべてのメタデータを取得します

契約（factorial_contracts({ action: 'list' })）：

• 返される項目：id、employee_id、job_title、effective_on（4 項目）
• デフォルトの上限：1 ページあたり 100 件の契約

すべての一覧操作で、ページネーションを制御するための page パラメーターと limit パラメーターを使用できます。

監査ログ

すべての書き込み操作（作成、更新、削除、承認、却下）は、次の内容とともに記録されます。

• タイムスタンプ
• 操作の種類
• エンティティの種類と ID
• 変更内容
• 成功または失敗、および所要時間

このログの範囲。 履歴は実行中のサーバープロセスのメモリ内に保持され、直近の 1000 件に制限されます。また、ツールやリソースを通じて公開されることはありません。プロセスが終了すると失われます。DEBUG=true を設定すると、各エントリがサーバーの stderr に書き込まれます。現時点で履歴を保持する唯一の方法です。これはデバッグ用であり、コンプライアンス記録ではありません。永続的で検索可能な監査履歴が必要な場合は、FactorialHR 独自のアクティビティログを正式な記録として使用してください。

開発

# Clone the repository
git clone https://github.com/t4dhg/mcp-factorial.git
cd mcp-factorial

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

# Run locally
FACTORIAL_API_KEY=your-key npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

プロジェクト構成

保守性を高めるため、コードベースはドメイン別のモジュールで構成されています。

src/
├── schemas/           # Zod schemas by domain
│   ├── employees.ts   # Employee, Team, Location, Contract schemas
│   ├── time-off.ts    # Leave, LeaveType, Allowance, Shift schemas
│   ├── projects.ts    # Project, Task, Worker, TimeRecord schemas
│   ├── training.ts    # Training, Session, Membership schemas
│   ├── ats.ts         # JobPosting, Candidate, Application schemas
│   └── ...
├── api/               # API functions by domain
│   ├── employees.ts   # listEmployees, getEmployee, createEmployee, etc.
│   ├── time-off.ts    # listLeaves, createLeave, approveLeave, etc.
│   ├── projects.ts    # listProjects, createProject, etc.
│   └── ...
├── tools/             # MCP tool registrations by domain
│   ├── employees.ts   # factorial_employees tool registration
│   ├── time-off.ts    # factorial_time_off tool registration
│   ├── index.ts       # Server setup, discovery tool, resources, prompts
│   └── ...
├── index.ts           # Entry point (re-exports from tools/)
├── api.ts             # Re-exports from api/
└── schemas.ts         # Re-exports from schemas/

新機能の追加：

1. スキーマを src/schemas/{domain}.ts に追加します
2. API 関数を src/api/{domain}.ts に追加します
3. ツールのアクションを src/tools/{domain}.ts に追加します
4. 必要に応じて、src/schemas/index.ts と src/api/index.ts のエクスポートを更新します
5. npm test を実行して確認します

トラブルシューティング

API キーが機能しない

• API キーに適切な権限があることを確認します
• キーが取り消されていないか、期限切れになっていないか確認します
• 環境変数にキーが正しく設定されていることを確認します

レート制限

サーバーはレート制限に対して指数バックオフを実装しています。頻繁に制限に達する場合は、次の方法を試してください。

• リクエストの頻度を下げる
• ページサイズを小さくしてページネーションを使用する
• キャッシュを無効化するパラメーターを避けて、キャッシュを有効にする

データが見つからない

• hired_on フィールド：FactorialHR API では、すべての従業員にこのフィールドが設定されるとは限りません
• チームへの所属：チームに割り当てられていない従業員もいます
• 空の応答：Factorial アカウントにリソースが存在するか確認します

ドキュメントをダウンロードできない

ドキュメントのダウンロードには、OAuth2 認証が必要です。これは Factorial API の制限です。ダウンロードエンドポイントでは API キー認証を受け付けません。

次のようなエラーが表示される場合：

「ドキュメントのダウンロードには OAuth2 認証が必要です」

OAuth2 認証情報を設定する必要があります。上記のOAuth2 の設定（ドキュメントのダウンロードに必要）を参照してください。

注意：OAuth2 リフレッシュトークンの有効期限は 1 週間です。ダウンロードが突然機能しなくなった場合は、再認証して新しいリフレッシュトークンを取得してください。

「ID X のドキュメントが見つかりません」エラー

Factorial API の個別ドキュメントエンドポイント（GET /documents/{id}）では、従業員固有のドキュメントへのアクセスに制限があります。これは次の理由によるものです。

1. employee_ids フィルターを使った list_documents は、すべての従業員ドキュメントを正しく返します
2. ID を指定した get_document では、同じドキュメントに個別にアクセスできません

回避策：download アクションではなく、download_payslips アクションを使用してください。download_payslips アクションは、一覧取得の操作からドキュメントのメタデータを直接使用することで、問題のある個別の GET エンドポイントを回避します。

// This works - uses document list internally
factorial_documents({
  action: 'download_payslips',
  employee_id: 123,
  output_dir: '/path/to/downloads',
});

よくある質問

Q: 給与・給与計算データは公開されますか？ A: 給与計算データ（各種手当、納税者番号、家族状況）は読み取り専用で利用できます。給与計算データに対する書き込み操作はサポートされていません。

Q: Claude は Factorial のデータを変更できますか？ A: はい。従業員、チーム、拠点、休暇、プロジェクト、研修、採用について、完全な CRUD 操作を利用できます。リスクの高い操作には明確なマークが付いています。

Q: データはどのようにキャッシュされますか？ A: データはメモリ内に TTL 付きでキャッシュされます。従業員（5 分）、チーム（10 分）、拠点（15 分）、契約（3 分）です。

Q: 使用される FactorialHR API のバージョンは何ですか？ A: デフォルトではバージョン 2026-07-01 です。FACTORIAL_API_VERSION 環境変数で変更できます。このバージョン以降、Factorial のすべての識別子（id および *_id フィールド）は数値ではなく文字列です。不透明な文字列として扱ってください。

Q: Claude に registro horario を入力してもらえますか？ A: はい。FACTORIAL_EMPLOYEE_ID を設定し、gaps を実行して未入力の日を確認した後、毎日のセグメントを指定して log_range を実行します。最初の呼び出しではプレビューとトークンが返され、2 回目の呼び出しで書き込みが行われます。勤怠と Registro Horario を参照してください。

Q: 書き込み操作は記録されますか？ A: はい。すべての書き込みは監査モジュールによって、タイムスタンプ、エンティティ、変更内容、結果とともに記録されます。ログは実行中のプロセスのメモリ内（直近 1000 件）に保存され、MCP インターフェース経由では取得できません。そのため、コンプライアンス記録ではなく、デバッグ用の補助として扱ってください。監査ログ を参照してください。

Factorial API の仕様と制限事項

FactorialHR API には、一般的な REST API とは異なる設計パターンがいくつかあります。この MCP サーバーではこれらを自動的に処理しますが、デバッグや拡張の際には理解しておくと役立ちます。

データの配置に関する仕様

データ	想定される場所	実際の場所	影響
チームへの所属	Employee オブジェクト（team_ids）	Team オブジェクト（employee_ids）	list_teams を使用して従業員の所属チームを確認します
職務の割り当て	Employee オブジェクト（job_role_id）	Contract オブジェクト（job_catalog_role_id）	get_employee_with_contract を使用して職務情報を確認します
給与情報	Employee オブジェクト	Contract オブジェクト（salary_amount、salary_frequency）	get_employee_with_contract を使用して給与を確認します
役職名	Employee オブジェクト	Contract オブジェクト（job_title）	Factorial で設定されていない場合は null になることがあります

エンドポイントに関する仕様

エンドポイント	仕様	回避策
GET /employees/{id}	有効な従業員でも 404 を返すことがあります	サーバーが全件を取得して絞り込みます
GET /documents/{id}	従業員固有のドキュメントで 404 を返すことがあります	この動作を回避する download_payslips を使用します
GET /contracts?employee_id=X	絞り込みの信頼性が低い	サーバーが全件を取得し、クライアント側で絞り込みます
空の結果	{"data": []} ではなく {"errors": null} を返します	サーバーはどちらの形式にも対応します
ドキュメントのダウンロード URL	OAuth2 が必要です（API キーは使用できません）	ダウンロードには OAuth2 認証情報を設定します

フィールドの利用可否

データが存在すると予想される場合でも、一部のフィールドは null になることがあります。

• job_title：従業員の契約で設定されている場合にのみ入力されます
• manager_id：報告系統が設定されている場合にのみ入力されます
• seniority_calculation_date：存在しない hired_on フィールドの代わりにこちらを使用してください
• ドキュメントのメタデータ（name、mime_type、size_bytes）：一部のドキュメントでは null になることがあります

給与データ

給与情報は Employee エンティティではなく、Contract エンティティで確認できます。

salary_amount: number (in cents, e.g., 7000000 = €70,000)
salary_frequency: 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly'

従業員データと最新の給与情報を取得するには、get_employee_with_contract を使用してください。

ベストプラクティス

1. 従業員の職務を取得する場合：get_employee の代わりに get_employee_with_contract を使用してください
2. 職務で従業員を検索する場合：職務 ID を指定して list_employees_by_job_role を使用してください
3. 従業員の所属チームを確認する場合：list_teams を照会し、employee_ids 配列を確認してください
4. 給与データを取得する場合：必ず従業員エンドポイントではなく、契約エンドポイントを使用してください

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT © Taig Mac Carthy

---

Anthropic による Model Context Protocol を使用して構築