Contractor Foreman by Cotlet

Contractor Foreman API とセルフホスト型 MCP サーバー

お使いのパソコンで、ご自身の Google Chrome のセッションを使って Python で実行する Contractor Foreman API と Contractor Foreman MCP サーバーです。Cotletで本番運用している Contractor Foreman の 89 個すべてのツールに対応しています。プロジェクト、スケジュール、日報、パンチリスト、ToDo、見積もり、変更注文、請求書、支払い、工事原価計算、ディレクトリ、見込み客、タイムカード、請求、発注書、下請け契約、作業指示書、サービスチケット、RFI、提出書類、検査などを扱えます。

Contractor Foreman には一般公開されている API も、公式 MCP サーバーもありません。このリポジトリでは、その両方を利用できます。

• Claude Code、Claude Desktop、Cursor、Codex およびあらゆる MCP クライアント向けの MCP サーバー。stdio または HTTP 経由で接続します。セットアップ
• http://127.0.0.1:8787/api/v1/contractor-foreman で利用できる REST API。OpenAPI ドキュメントは /docs にあります。セットアップ
• Python：call("list_projects", search="Oak St") に加え、すぐに使えるスクリプト 10 個を examples/ に用意しています。

このツールは、自分で実行したい技術者向けです。非商用利用に限ります（ライセンス）。サーバー上で 24 時間 365 日稼働させたい場合、Contractor Foreman がアプリを変更しても動作する状態を保ちたい場合、チームやビジネスで利用したい場合は、cotlet.dev のホステッド版をご利用ください。

git clone https://github.com/cotletdev/contractor-foreman-api-mcp-server.git && cd contractor-foreman-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
contractor-foreman-mcp connect                     # reads your Contractor Foreman session from Chrome
contractor-foreman-mcp call list_projects
claude mcp add contractor-foreman -- "$PWD/.venv/bin/contractor-foreman-mcp" mcp

目次

• 仕組み
• 必要条件
• インストール
• Chrome への接続
• MCP サーバー
• REST API
• Python とサンプルスクリプト
• 89 個すべてのツール
• 設定
• セキュリティと Contractor Foreman アカウント
• エラー
• セルフホスト版とホステッド版
• よくある質問
• ライセンス

仕組み

AI agent (MCP) / script (REST, Python) ──▶ contractor-foreman-mcp on your computer ──your cookies──▶ app.contractorforeman.net
                                                      ▲
                     contractor-foreman-mcp connect ──┘ reads them once from your Chrome (DevTools Protocol)

1. いつもと同じように、ご自身の Chrome で Contractor Foreman にサインインします。
2. contractor-foreman-mcp connect は Chrome DevTools Protocol 経由でその Chrome に接続し、contractorforeman.net の Cookie とブラウザーのタイムゾーンを読み取って、~/.config/contractor-foreman-api-mcp/session.json に保存します。このファイルを読み取れるのはご自身のユーザーだけです。パスワードを確認したり保存したりすることはありません。
3. 各ツール呼び出しは、Contractor Foreman のウェブアプリが呼び出すものと同じ /api/... エンドポイントへのリクエストです。Cookie を付けて、Chrome の TLS フィンガープリントを再現する curl_cffi で送信します。呼び出しのたびにブラウザーを起動することはありません。

Contractor Foreman は、サインアウト状態でのリクエストにも HTTP 200 と「サインアウト済み」を示す本文を返します。ツールはこれを auth_expired に変換します。その後、Chrome がリモートデバッグを有効にして起動していれば、サーバーは Chrome から Cookie を再度読み取ります。送信する時刻は、connect が Chrome から読み取ったタイムゾーンで保存されます。

必要条件

• Python 3.11 以降。
• Contractor Foreman にサインイン済みの Google Chrome 144 以降。デバッグポートを使用する場合は、任意の Chrome または Chromium を利用できます（オプション B：デバッグポートを使用する Chrome）。
• macOS、Linux、または Windows。
• 使用するモジュールへのアクセス権を持つ Contractor Foreman のロール。ロールで開けないモジュールのツールを使うと、アプリ本来のメッセージが表示されて失敗します。

インストール

git clone https://github.com/cotletdev/contractor-foreman-api-mcp-server.git
cd contractor-foreman-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
contractor-foreman-mcp --version

uv を使う場合：uv venv && uv pip install -e . を実行してから、uv run contractor-foreman-mcp ... を実行します。

AI エージェント（Claude Code、Codex、Cursor）を使ってセットアップしますか？このフォルダーを開いて、リポジトリのセットアップを依頼してください。AGENTS.md にすべての手順が記載されており、Chrome での操作が必要なときだけ確認を求めます。

更新するには、git pull && pip install -e . を実行します。ホストされている Contractor Foreman ツールへの変更はすべて、このリポジトリに反映しています。

Chrome を接続する

オプション A：普段使っている Chrome（推奨）

1. Chrome で chrome://inspect/#remote-debugging を開き、remote debugging をオンにします。すると Chrome は、このコンピューター上のプログラムからの DevTools 接続を受け付け、接続のたびに確認を求めます。

2. app.contractorforeman.net にサインインしていることを確認します。

3. 次を実行します。

   contractor-foreman-mcp connect
   

4. Chrome で接続を許可するか確認されます。Allow をクリックします。

Saved 34 Contractor Foreman cookies to /Users/you/.config/contractor-foreman-api-mcp/session.json
Signed in to Contractor Foreman as Mike Turner ([email protected])

その後、リモートデバッグをオフに戻してもかまいません。Contractor Foreman にサインアウトされた後、新しいセッションをサーバーに自動で取得させたい場合は、オンのままにしてください。

connect は、Chrome のデフォルトのプロファイルフォルダーにある DevToolsActivePort ファイルを探します。Chrome Beta、Canary、またはカスタムのプロファイルフォルダーを使用する場合は、--profile-dir "<folder>" を指定してください。

オプション B：デバッグポートを使う Chrome

Chrome はデフォルトのプロファイルではデバッグポートを開かないため、別のプロファイルで Chrome を起動し、そこで一度 Contractor Foreman にサインインしてから接続します。

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-contractor-foreman"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-contractor-foreman"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-contractor-foreman"

contractor-foreman-mcp connect --cdp http://127.0.0.1:9222

--cdp には ws:// の DevTools URL も指定できます。たとえば、SSH トンネル経由で接続する別のコンピューター上の Chrome の URL を指定できます。

オプション C：Cookie を手動で貼り付ける

Chrome を使えないサーバーの場合：Chrome で app.contractorforeman.net の DevTools を開き、Application > Cookies を選択して、2 つの値をコピーします。_session__240322（https://app.contractorforeman.net の下）と auth_data_session（.contractorforeman.net の下）です。その後、次を実行します。

contractor-foreman-mcp connect --token     # paste "_session__240322=...; auth_data_session=...", input is hidden
# or, without a session file:
export CONTRACTOR_FOREMAN_AUTH_TOKEN='_session__240322=...; auth_data_session=...'

貼り付けた Cookie は自動更新されません。Contractor Foreman にサインアウトされたら、新しい Cookie を貼り付けてください。Chrome がない場合、タイムゾーンにはこのコンピューターの設定（TZ またはシステム設定）が使われます。

セッションはいつでも次のコマンドで確認できます。

contractor-foreman-mcp status

MCP サーバー

MCP サーバーでは、すべてのツールの入力スキーマ、エージェント向けの説明、ヒントを確認できます。読み取りツールには読み取り専用の印が付き、クライアント宛てに書類をメール送信するツールには、実行前にクライアントが確認を求めるよう印が付きます。

Claude Code

claude mcp add contractor-foreman -- /path/to/contractor-foreman-api-mcp-server/.venv/bin/contractor-foreman-mcp mcp
# read only:
claude mcp add contractor-foreman -- /path/to/contractor-foreman-api-mcp-server/.venv/bin/contractor-foreman-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "contractor-foreman": {
      "command": "/path/to/contractor-foreman-api-mcp-server/.venv/bin/contractor-foreman-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json。Claude Desktop と同じブロックを使用します。すぐに使えるコピーは mcp.json にあります。

Codex

~/.codex/config.toml：

[mcp_servers.contractor-foreman]
command = "/path/to/contractor-foreman-api-mcp-server/.venv/bin/contractor-foreman-mcp"
args = ["mcp"]

HTTP 経由

contractor-foreman-mcp serve を実行すると、URL を受け取るクライアント向けに、ストリーミング可能な HTTP 経由でも http://127.0.0.1:8787/mcp で MCP を提供します。

contractor-foreman-mcp serve
claude mcp add --transport http contractor-foreman http://127.0.0.1:8787/mcp

その後、エージェントに次のようなことを依頼できます。

Maple St の改装工事について、Mike のボイスメモがあります。今日の日報にまとめてください：大工チーム4人、電気工事士1人、乾式壁を搬入、雨のため午後2時30分に作業中止。

Johnson 様宅の浴室の現地確認で作成したこの作業範囲リストから、材料に20％の上乗せを適用した見積書を作成し、合計を表示してから、クライアントにメールで送信してください。

見積もりを超過している原価コードがある進行中のプロジェクトはどれですか？超過額の大きい順に表示してください。

支払い期限を過ぎた請求書を、残高と延滞日数とともに一覧表示し、Burger Palace からの1,200ドルの小切手を請求書11に記録してください。

REST API

contractor-foreman-mcp serve       # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

各ツールには /api/v1/contractor-foreman 配下に個別のルートがあり、cotlet.dev のホスト版 API とパスが同じなので、一方に向けて書いたコードはもう一方でも動作します。パスの各部分とクエリ文字列が引数となり、JSON ボディで残りの引数を指定します。

curl 'http://127.0.0.1:8787/api/v1/contractor-foreman/projects?search=Oak%20St'
curl 'http://127.0.0.1:8787/api/v1/contractor-foreman/projects/1678164/job-costing'
curl 'http://127.0.0.1:8787/api/v1/contractor-foreman/invoices?unpaid_only=true'
curl -X POST http://127.0.0.1:8787/api/v1/contractor-foreman/daily-logs \
  -H 'Content-Type: application/json' \
  -d '{"project_id": "1678164", "date": "2026-10-20", "notes": "Hung and taped drywall in the dining area.", "people": {"Drywall crew": 3}}'

名前で指定する任意のツール。ボディを引数として渡します。

curl -X POST http://127.0.0.1:8787/api/v1/contractor-foreman/tools/list_todos -d '{"status": "open"}'

• GET /api/v1/contractor-foreman/tools：各ツールのルート、入力スキーマ、回答例を表示します。
• GET /docs：対話型の OpenAPI ドキュメントです。GET /openapi.json は n8n、Postman、または生成したクライアント向けのスキーマです。
• 回答は JSON 形式です。リストには next_cursor が含まれます。次のページを取得するには、それを cursor として渡してください。

サーバーは 127.0.0.1 のみで待ち受けます。別のデバイスからアクセスするにはトークンを設定してください。その場合、すべてのリクエストに Authorization: Bearer <token> が必要です。

CONTRACTOR_FOREMAN_MCP_TOKEN=$(openssl rand -hex 24) contractor-foreman-mcp serve --host 0.0.0.0

Python とサンプルスクリプト

サーバーなしで、Python から直接実行できます。

from contractor_foreman_api_mcp import call
from contractor_foreman_api_mcp.scripting import paginate, write_rows

projects = list(paginate("list_projects", {"include_completed": True, "limit": 100}, "projects"))
write_rows(projects, "projects.csv")
costing = call("get_job_costing", project_id=projects[0]["project_id"])
call("create_daily_log", project_id=projects[0]["project_id"], date="2026-10-20", notes="Framed the east wall.")

または、シェルから単一のツールを実行できます。例：contractor-foreman-mcp call list_invoices unpaid_only=true limit=10。JSON オブジェクトを使うこともできます。

examples/ にすぐ使えるスクリプトがあります。それぞれ JSON または簡潔なレポートを出力し、必要に応じて --out file.csv または --out file.json を指定できます。また、--help も使えます。

スクリプト	内容
export_projects.py	プロジェクトを CSV または JSON に出力します。顧客、段階、日付、契約金額、コスト、完成率が含まれます。--status、--search を指定できます。
add_daily_log.py	現場メモ、作業班、納品情報から日報を作成します。対象日に日報がまだないことを確認してから作成します。--dry-run を指定できます。
create_estimate.py	マークアップを適用し、CSV の作業範囲リストから見積もりを作成します。合計金額を出力し、--send を指定すると PDF をメールで送信します。
create_change_order.py	顧客の依頼から変更注文または変更注文依頼を作成します。保存済みの変更注文をメールで送信するには --send を指定します。
reschedule_task.py	スケジュールタスクと、それに依存するすべてのタスクを N 日移動します。--dry-run を指定できます。
over_budget_projects.py	実コストが見積もりを超えている進行中プロジェクトのコストコードを、超過額の大きい順に表示します。
overdue_invoices.py	残高のある延滞請求書を、古い順に表示します。延滞日数と未払い総額も表示します。
record_payment.py	請求書番号で特定した請求書に対する小切手または振込を記録し、新しい残高を表示します。
crew_hours.py	タイムカードから、過去 N 日間または指定期間のプロジェクト別・従業員別の労働時間と人件費を表示します。
open_todos.py	次の N 日以内に期限を迎える、または期限を過ぎた未完了の ToDo をプロジェクト別に表示します。

python examples/overdue_invoices.py --out overdue.csv
python examples/add_daily_log.py --project-id 1678164 --notes "Framed second floor east wall." --people "Framing crew=4" --dry-run

スケジュールを設定する場合、コンピューターの電源が入っていれば、ローカルの cron を利用できます。例：0 8 * * 1 cd ~/contractor-foreman-api-mcp-server && .venv/bin/python examples/overdue_invoices.py --out overdue.csv。

89 個すべてのツール

ID はツール一覧から取得します。例：list_projects の project_id、list_invoices の invoice_id などです。contractor-foreman-mcp tools で一覧を表示でき、contractor-foreman-mcp tools --json で入力スキーマも表示できます。ホスト版に含まれるすべてのツールがこのリポジトリにあります。

プロジェクト、スケジュール、日次ログ、パンチリスト、ToDo（18）

ツール	アクセス	REST ルート	機能
create_daily_log	書き込み	POST /daily-logs	プロジェクトの日次ログを新規作成します。作業メモ、作業者、納品、天候に関するメモ、遅延を記録します。
create_project	書き込み	POST /projects	顧客の新規プロジェクトを作成します。プロジェクト番号、種類、段階、住所、日付を指定します。
create_punchlist	書き込み	POST /punchlists	プロジェクトに空のパンチリストを新規作成します。
create_todo	書き込み	POST /todos	ToDoを新規作成します。任意でプロジェクトに関連付け、期限、優先度、担当者を設定できます。
get_daily_log	読み取り	GET /daily-logs/{daily_log_id}	1件の日次ログを取得します。作業メモ、作業者と訪問者、資材、機器、天候、遅延を確認できます。
get_job_costing	読み取り	GET /projects/{project_id}/job-costing	1つのプロジェクトについて、原価コードごとの見積原価と実際原価、差額、合計を取得します。
get_project	読み取り	GET /projects/{project_id}	1件のプロジェクトを取得します。顧客、住所、段階、日付、契約金額、原価、請求、留保金を確認できます。
get_punchlist	読み取り	GET /punchlists/{punchlist_id}	1件のパンチリストを取得します。プロジェクト、住所、顧客、未完了および完了項目の件数を確認できます。
get_todo	読み取り	GET /todos/{todo_id}	1件のToDoを取得します。説明、プロジェクト、優先度、ステータス、期限、担当者、チェックリストを確認できます。
list_daily_logs	読み取り	GET /daily-logs	日付で日次ログを一覧表示します。任意でプロジェクトと期間を指定できます。
list_projects	読み取り	GET /projects	顧客、段階、日付、契約金額、原価、進捗率を含むプロジェクトを一覧表示します。
list_punchlists	読み取り	GET /punchlists	プロジェクト、ステータス、未完了および完了項目の件数、各項目の担当者を含むパンチリストを一覧表示します。
list_schedule_tasks	読み取り	GET /projects/{project_id}/schedule-tasks	プロジェクトのガントスケジュールのタスクを一覧表示します。日付、期間、依存関係、担当者、進捗率を確認できます。
list_todos	読み取り	GET /todos	プロジェクト、優先度、ステータス、期限、担当者を含むToDoを一覧表示します。
update_daily_log	書き込み	PATCH /daily-logs/{daily_log_id}	日次ログのメモ、時刻、作業者、納品、天候に関するメモ、遅延を変更します。
update_project	書き込み	PATCH /projects/{project_id}	プロジェクトの名前、段階、種類、住所、日付、説明を変更します。
update_schedule_task	書き込み	PATCH /projects/{project_id}/schedule-tasks/{task_id}	プロジェクトのスケジュールにあるタスクの名前、日付、期間、進捗率を変更します。
update_todo	書き込み	PATCH /todos/{todo_id}	ToDoの名前、説明、期限、優先度、ステータスを変更します。たとえば、完了としてマークできます。

見積もり、変更注文、請求書、支払い（27）

ツール	アクセス	REST ルート	機能
add_change_order_items	書き込み	POST /change-orders/{change_order_id}/items	変更注文または変更注文リクエストに、価格付きの項目を追加します。
add_estimate_items	書き込み	POST /estimates/{estimate_id}/items	既存の見積もりに、価格付きの項目を追加します。
add_invoice_items	書き込み	POST /invoices/{invoice_id}/items	請求書に、価格付きの項目を追加します。
create_change_order	書き込み	POST /change-orders	プロジェクトに、項目を含む変更注文または変更注文リクエストを作成します。
create_estimate	書き込み	POST /estimates	プロジェクトまたは顧客向けに、価格付きの項目を含む見積もりの下書きを作成します。
create_invoice	書き込み	POST /invoices	プロジェクトまたは顧客向けに、価格付きの項目を含む請求書の下書きを作成します。
create_share_link	書き込み	POST /share-links	サインイン済みのチームが見積もり、変更注文、請求書を開ける、短い内部リンクを作成します。
delete_change_order	書き込み	DELETE /change-orders/{change_order_id}	変更注文または変更注文リクエストを完全に削除します。
delete_estimate	書き込み	DELETE /estimates/{estimate_id}	見積もりを完全に削除します。
delete_invoice	書き込み	DELETE /invoices/{invoice_id}	支払いがない請求書を完全に削除します。
get_change_order	読み取り	GET /change-orders/{change_order_id}	変更注文またはリクエスト1件の説明、ステータス、合計、項目を取得します。
get_estimate	読み取り	GET /estimates/{estimate_id}	顧客、日付、条件、合計、すべての項目を含む見積もり1件を取得します。
get_invoice	読み取り	GET /invoices/{invoice_id}	顧客、日付、条件、項目、支払い、未払い残高を含む請求書1件を取得します。
list_change_orders	読み取り	GET /change-orders	変更注文と変更注文リクエストを新しい順に、ステータス、プロジェクト、合計とともに一覧表示します。
list_cost_codes	読み取り	GET /cost-codes	見積もり、変更注文、請求書の項目に指定する、会社のコストコードを一覧表示します。
list_cost_items	読み取り	GET /cost-items	見積もりと変更注文の項目の価格設定に使う、単位、単価、マークアップ付きの保存済みコスト項目を一覧表示します。
list_estimates	読み取り	GET /estimates	見積もりを新しい順に、ステータス、プロジェクト、顧客、合計とともに一覧表示します。
list_invoices	読み取り	GET /invoices	請求書を新しい順に、ステータス、合計、未払い残高、延滞フラグとともに一覧表示します。
list_payments	読み取り	GET /payments	請求書に対して受領した支払いを新しい順に、金額、方法、請求書とともに一覧表示します。
record_payment	書き込み	POST /invoices/{invoice_id}/payments	請求書に対して受領した支払いを記録します。
remove_estimate_items	書き込み	DELETE /estimates/{estimate_id}/items	見積もりから項目を削除します。
send_change_order	書き込み	POST /change-orders/{change_order_id}/send	変更注文をPDFとして顧客または指定した宛先にメールで送信します。
send_estimate	書き込み	POST /estimates/{estimate_id}/send	見積もりをPDFとして顧客または指定した宛先にメールで送信します。
send_invoice	書き込み	POST /invoices/{invoice_id}/send	請求書をPDFとして顧客または指定した宛先にメールで送信します。
update_change_order	書き込み	PATCH /change-orders/{change_order_id}	変更注文のステータス、タイトル、理由、日付を変更します。
update_estimate	書き込み	PATCH /estimates/{estimate_id}	見積もりのステータス、タイトル、日付、説明、含まれる項目、除外項目を変更します。
update_invoice	書き込み	PATCH /invoices/{invoice_id}	請求書のステータス、請求日、支払期日、説明を変更します。

ディレクトリ、リード、タイムカード、購買、現場作業（44）

ツール	アクセス	REST ルート	機能
add_project_note	write	POST /projects/{project_id}/notes	プロジェクトの「Notes」タブにメモを追加します。
create_bill	write	POST /bills	任意でプロジェクトに紐付けて、明細項目を含む仕入先の請求書を記録します。
create_contact	write	POST /contacts	顧客、従業員、請負業者、仕入先、その他の連絡先をディレクトリに追加します。
create_expense	write	POST /expenses	金額、日付、仕入先、プロジェクトを含む経費（領収書、購入、手数料）を記録します。
create_inspection	write	POST /inspections	種類、日付、機関、検査担当者、メモを指定して、プロジェクトの検査を記録します。
create_lead	write	POST /leads	連絡先情報と営業パイプラインのステージを指定して、営業リードを追加します。
create_opportunity	write	POST /opportunities	ステージ、スコア、予算、販売予定日を指定して、顧客の営業案件を追加します。
create_purchase_order	write	POST /purchase-orders	明細項目を含む仕入先宛ての購入注文書をドラフトとして作成します。任意でプロジェクトに紐付けられます。
create_rfi	write	POST /rfis	質問と回答期限を指定して、プロジェクトの情報提供依頼をドラフトとして作成します。
create_service_ticket	write	POST /service-tickets	顧客のサービスチケットを作成します。任意で日時を指定して予定を設定できます。
create_sub_contract	write	POST /sub-contracts	プロジェクトの下請業者との下請契約をドラフトとして作成します。
create_work_order	write	POST /work-orders	件名、説明、日付を指定して、プロジェクトのステータスが「Open」の作業指示書を作成します。
get_bill	read	GET /bills/{bill_id}	仕入先の請求書1件の明細項目、日付、合計金額、未払残高、ステータスを取得します。
get_clock_status	read	GET /clock-status	現在出勤記録中の人、自分が出勤記録中かどうか、今週と先週の作業員の労働時間を取得します。
get_contact	read	GET /contacts/{contact_id}	ディレクトリのレコード1件を詳細に取得します。連絡先情報、ステータス、サービス、取引条件、追加の連絡先が含まれます。
get_expense	read	GET /expenses/{expense_id}	金額、日付、仕入先、プロジェクト、原価種別、原価コード、理由を含む経費1件を取得します。
get_inspection	read	GET /inspections/{inspection_id}	種類、プロジェクト、日付、結果、機関、検査担当者、メモを含む検査1件を取得します。
get_opportunity	read	GET /opportunities/{opportunity_id}	営業案件1件の詳細を取得します。顧客の連絡先、ステージ、スコア、予算、メモ、最終アクティビティが含まれます。
get_purchase_order	read	GET /purchase-orders/{purchase_order_id}	仕入先、日付、ステータス、明細項目を含む購入注文書1件を取得します。
get_rfi	read	GET /rfis/{rfi_id}	質問、日付、回答、ステータスを含む情報提供依頼1件を取得します。
get_service_ticket	read	GET /service-tickets/{service_ticket_id}	顧客、サービス提供先住所、予定、技術者、優先度を含むサービスチケット1件を取得します。
get_sub_contract	read	GET /sub-contracts/{sub_contract_id}	下請業者、金額、留保金、作業範囲、項目を含む下請契約1件を取得します。
get_submittal	read	GET /submittals/{submittal_id}	図面シート、仕様書のセクション、ステータス、日付、項目を含む提出物1件を取得します。
get_time_card	read	GET /time-cards/{timecard_id}	従業員ごとの時間と原価コードを含むタイムカードまたは作業員シート1件を取得します。
get_work_order	read	GET /work-orders/{work_order_id}	プロジェクト、顧客、ステータス、日付、場所、メモ、項目を含む作業指示書1件を取得します。
list_bills	read	GET /bills	仕入先、プロジェクト、日付、合計金額、未払残高、ステータスを含む仕入先の請求書を一覧表示します。
list_contacts	read	GET /contacts	ディレクトリの顧客、従業員、請負業者、仕入先、その他の連絡先を一覧表示します。
list_expenses	read	GET /expenses	金額、日付、仕入先、プロジェクト、原価種別、支払者を含む経費を一覧表示します。
list_inspections	read	GET /inspections	プロジェクト、種類、日付、結果、機関、許可番号を含む検査を一覧表示します。
list_leads	read	GET /leads	連絡先情報、ステージ、品質スコアを含む営業リードを一覧表示します。
list_opportunities	read	GET /opportunities	顧客、ステージ、スコア、予算、販売予定日を含む営業案件を一覧表示します。
list_project_crew_hours	read	GET /projects/{project_id}/crew-hours	1つのプロジェクトで記録された時間と人件費を、従業員、日、原価コードごとに一覧表示します。
list_project_files	read	GET /projects/{project_id}/files	名前、サイズ、ダウンロードリンクを含む、プロジェクトの写真とドキュメントを一覧表示します。
list_project_notes	read	GET /projects/{project_id}/notes	作成者と時刻を含む、プロジェクトの「Notes」タブのメモを一覧表示します。
list_purchase_orders	read	GET /purchase-orders	仕入先、プロジェクト、注文日、合計金額、ステータスを含む購入注文書を一覧表示します。
list_rfis	read	GET /rfis	質問、プロジェクト、日付、回答、ステータスを含む情報提供依頼を一覧表示します。
list_service_tickets	read	GET /service-tickets	顧客、ステータス、サービス提供日時、技術者を含むサービスチケットを一覧表示します。
list_sub_contracts	read	GET /sub-contracts	下請業者、プロジェクト、金額、請求済み額、支払済み額、残高、ステータスを含む下請契約を一覧表示します。
list_submittals	read	GET /submittals	プロジェクト、ステータス、受領日、期限日、承認者を含む提出物を一覧表示します。
list_time_cards	read	GET /time-cards	従業員または作業員、プロジェクト、出勤・退勤時刻、労働時間を含むタイムカードを新しい順に一覧表示します。
list_work_orders	read	GET /work-orders	プロジェクト、顧客、ステータス、日付、合計金額、担当者を含む作業指示書を一覧表示します。
record_inspection_result	write	PUT /inspections/{inspection_id}/result	任意でメモを添えて、検査を合格、不合格、または再検査に設定します。
update_service_ticket_status	write	PUT /service-tickets/{service_ticket_id}/status	サービスチケットのステータスを「scheduled」「en route」「checked in」「completed」「closed」などに変更します。
update_work_order_status	write	PUT /work-orders/{work_order_id}/status	作業指示書のステータスを「open」「estimating」「submitted」「approved」「canceled」「completed」に変更します。
意図的に実装していない機能：Contractor Foreman のサインイン、パスワード、メールアドレス、2 要素認証の設定、会社設定、サブスクリプションと請求、およびデモデータの切り替えです。すべてのリクエストはガードを通過し、これらの Contractor Foreman のパスへのアクセスは拒否されます。

設定

変数	デフォルト	説明
CONTRACTOR_FOREMAN_MCP_HOME	~/.config/contractor-foreman-api-mcp	session.json の保存フォルダーです。
CONTRACTOR_FOREMAN_AUTH_TOKEN		contractor-foreman-mcp connect の代わりに使用する、_session__240322=...; auth_data_session=... 形式のセッション Cookie です。
CONTRACTOR_FOREMAN_PROXY		Contractor Foreman へのすべてのリクエストに使用するプロキシです。例：http://user:pass@host:port。
CONTRACTOR_FOREMAN_MCP_READ_ONLY		1 にすると、Contractor Foreman を変更するすべてのツールが非表示になり、実行も拒否されます（--read-only と同じです）。
CONTRACTOR_FOREMAN_MCP_TOKEN		serve で必要なベアラートークンです。127.0.0.1 以外で待ち受ける場合に必要です。
CONTRACTOR_FOREMAN_MCP_HOST, CONTRACTOR_FOREMAN_MCP_PORT	127.0.0.1, 8787	serve のアドレスです。

セキュリティと Contractor Foreman アカウント

• パスワードがこのコードに渡ることはありません。 読み取られるのは Cookie のみで、対象も contractorforeman.net の Cookie だけです。
• セッションファイルはご自身で管理します。 session.json はモード 0600 で作成されます。このファイルを持つ人は誰でも Contractor Foreman でご本人として操作できるため、git や共有フォルダーには置かないでください。
• デフォルトではローカルのみです。 serve は 127.0.0.1 にバインドし、CONTRACTOR_FOREMAN_MCP_TOKEN が設定されていない場合、別のアドレスでの待ち受けを拒否します。
• アクセス先は contractorforeman.net のみです。 他のホストへのリクエストやリダイレクトは拒否されます。
• 読み取り専用モード。 --read-only または CONTRACTOR_FOREMAN_MCP_READ_ONLY=1 を指定すると、48 個の読み取りツールのみが公開されます。
• 一部の操作はクライアントに影響します。 send_estimate、send_change_order、send_invoice は、ご自身のアカウントから PDF をメール送信します。また、新しい ToDo は担当者のアプリに表示されます。MCP クライアントはこれらの操作を実行する前に確認を求めますが、スクリプトは確認しません。まずテストプロジェクトでお試しください。
• 削除すると元に戻せません。 delete_estimate、delete_change_order、delete_invoice は、アプリで削除した場合と同様にレコードを削除します。

エラー

REST API は {"error": "<code>", "message": "..."} を返します。MCP サーバーは同じコードとメッセージをツールエラーとして返します。

ステータス	コード	対処方法
401	auth_required, auth_expired	セッションがないか、Contractor Foreman からサインアウトされています。Chrome でサインインしてから、contractor-foreman-mcp connect を実行してください。
403	app_permission_denied	お使いの Contractor Foreman のロールでは、そのモジュールを開けません。
403	scope_denied	サーバーが読み取り専用で実行されているか、アカウント設定または請求を変更するリクエストです。
403	target_blocked	Contractor Foreman がリクエストを拒否したか、ボット確認画面を表示しました。Chrome でアプリを一度開いてから、再試行してください。
409	captcha_required	Contractor Foreman が CAPTCHA を求めています。Chrome で解決してください。
422	invalid_input	引数が不足しているか、正しくありません。メッセージに該当する引数が示されます。
429	rate_limited	Contractor Foreman によってアカウントへのリクエストが制限されています。数分待ってください。
502	target_error	Contractor Foreman がエラーを返しました（メッセージにその内容が引用されています）、またはアプリが変更されました。最新のツールを取得するには git pull を実行するか、問題を報告してください。

セルフホストまたはホスト版

	このリポジトリ	Cotlet、ホスト版
ツール	同じ89個	同じ89個
稼働場所	コンピューター上（電源が入っている間）	クラウド上、24時間365日
Contractor Foreman のセッション	お使いの Chrome、Cookie はローカルファイルに保存	EU 内のお客様専用 Cloud Browser、プロファイルは AES-256-GCM で暗号化
Contractor Foreman がアプリを変更した場合	修正後に一度 git pull	こちらで修正し、すべてのツールを毎日テスト
承認	MCP クライアントが呼び出しごとに確認	クライアントへのメール送信はお客様の承認待ち。ツールごとに切り替え可能
対応環境	お使いのマシン上の MCP クライアント、ローカルスクリプト	Claude.ai および ChatGPT のコネクター、n8n、Make、Zapier、あらゆる HTTP クライアント
利用対象	非商用利用のお客様	チーム、企業、代理店
価格	無料	クレジットカード不要の無料7日間トライアル（2,000クレジット付き）。その後は5,000クレジットで29ドルからの買い切りパック

ホスト版では、成功した呼び出しは20～30クレジット（ほとんどのツールでは25クレジット）を消費し、失敗した呼び出しは無料です。また、Cloud Browser でエージェント向けのアプリを有効にしている間は、1日あたり50クレジットを消費します。料金の詳細。

FAQ

Contractor Foreman には公式 API がありますか？ 一般公開されているものはありません。REST API、開発者向けドキュメント、API キーはありません（2026 年 10 月 11 日に確認）。プログラムからアクセスする方法は、リード、顧客、ファイルのアップロードに関する 7 つのトリガーと、「Create Lead」「Create Customer」の 2 つのアクションを備えた Zapier アプリのみです。見積もり、変更指示書、日報、スケジュール、請求書、工事原価を読み取ったり、書き込んだりすることはできません。詳細：cotlet.dev/integrations/contractor-foreman-api-mcp-server。

Claude、ChatGPT、Cursor 向けの Contractor Foreman MCP サーバーはありますか？ はい。この MCP サーバーはお使いのマシン上で動作します。Claude Code、Claude Desktop、Cursor、Codex では contractor-foreman-mcp mcp を実行してください。ChatGPT と Claude.ai のコネクタには公開 HTTPS URL が必要です。ホスト型 Contractor Foreman MCP サーバーを利用すると、その URL を取得できます。

これはスクレイパーですか？ スクレイパーを使う目的としてよく挙げられる機能（プロジェクト、請求書、タイムカードの CSV へのエクスポート）を備えていますが、HTML は解析しません。お使いのアカウントで、Contractor Foreman のウェブアプリと同じ JSON エンドポイントを呼び出します。

プロジェクト、請求書、作業員の労働時間を CSV にエクスポートできますか？ はい。python examples/export_projects.py --out projects.csv、python examples/overdue_invoices.py --out overdue.csv、または python examples/crew_hours.py --days 30 --out hours.csv を実行してください。ページは自動的にたどられます。

エージェントに日報を書かせることはできますか？ はい。create_daily_log には、メモ、作業員（人数を含む）、納品情報、天候に関する備考を指定できます。天候情報は Contractor Foreman が日付と住所に基づいて記録します。examples/add_daily_log.py は、まずその日に日報がまだ作成されていないことを確認します。

なぜ Chrome が必要なのですか？ パスワードを使わずに Contractor Foreman のセッションを読み取るためです。Chrome はサインインごとに一度だけ使用し、呼び出しごとには使用しません。

Contractor Foreman からサインアウトされた場合はどうなりますか？ 呼び出しは auth_expired エラーで失敗します。Chrome のリモートデバッグが有効になっている場合、次の呼び出しでサーバーが新しい Cookie を読み取ります（Chrome から確認を求められたら「許可」をクリックしてください）。そうでない場合は、再度 contractor-foreman-mcp connect を実行してください。

VPS や Docker で実行できますか？ 技術的には可能です。CONTRACTOR_FOREMAN_AUTH_TOKEN を使用してください。その場合、Contractor Foreman にはデータセンターの IP アドレスからのセッションとして認識されるため、ご本人の利用とは見なされにくくなります。常時稼働させる場合は、ホスト版を使うと、固定 IP のご自身専用 Cloud Browser にセッションを保持できます。

職場や顧客のために利用できますか？ いいえ。ライセンスで認められているのは非商用利用のみで、請負業を営むご自身の事業で実行することも業務利用に該当します。チーム、企業、顧客の業務で使用する場合は、Cotlet を利用するか、[email protected] にお問い合わせください。

オープンソースですか？ ソースコードは公開されていますが、ライセンスはオープンソースライセンスではありません。非商用利用のみで、業務利用は禁止されています。

ツールが動かなくなった場合や、別のツールが必要な場合はどうすればよいですか？ ツール名とエラーメッセージを添えて、イシューを作成してください。

ライセンス

PolyForm Noncommercial License 1.0.0。要約：

• 許可されていること： 非商用利用。ご自身の Contractor Foreman アカウントを使った個人的な目的での利用、または慈善団体、学校、公的研究機関、政府機関による利用。コードの変更、および同じライセンスでの共有。
• 許可されていないこと： ご自身の事業を含むあらゆる商用利用、顧客の業務での利用、販売や提供、および本ソフトウェアを基盤とするサービスの販売や提供。

---

Cotlet（@cotletdev）がメンテナンスしています。Contractor Foreman は、その所有者の商標です。このプロジェクトは非公式であり、Contractor Foreman との提携関係はなく、同社による推奨や後援も受けていません。