Contractor Foreman by Cotlet

Contractor Foreman API 和 MCP 服务，可自托管

一个 Contractor Foreman API 和一个 Contractor Foreman MCP 服务，使用 Python 在你自己的电脑上运行，并使用你自己的 Google Chrome 会话。包含我们在 Cotlet 生产环境中运行的全部 89 个 Contractor Foreman 工具：项目、日程、每日日志、整改清单、待办事项、估算、变更单、发票、付款、项目成本核算、目录、潜在客户、工时卡、账单、采购订单、分包合同、工作单、服务工单、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")，另附 examples/ 中的 10 个即用脚本。

本项目面向希望自行运行的技术人员，仅供非商业用途（许可证）。如果你希望在服务器上 24/7 运行，并在 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. 每次工具调用都会使用这些 Cookie，向 Contractor Foreman Web 应用调用的相同 /api/... 端点发送请求。请求通过 curl_cffi 发送，它会复制 Chrome 的 TLS 指纹。工具调用时不会运行浏览器。

当 Contractor Foreman 收到未登录请求时，会返回 HTTP 200 和一个内容为“已退出登录”的响应体，工具会将其转换为 auth_expired。如果 Chrome 已打开并启用了远程调试，服务会再次从 Chrome 读取 Cookie。你发送的时间会按 connect 从 Chrome 读取的时区保存。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，且已登录 Contractor Foreman。任何 Chrome 或 Chromium 浏览器都可以配合调试端口使用。
• 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 Agent（Claude Code、Codex、Cursor）设置？在此文件夹中打开项目，然后让它设置仓库：AGENTS.md 列出了每个步骤，它只会在 Chrome 中需要操作时询问你。

更新方式：git pull && pip install -e .。我们会将 Contractor Foreman 托管工具的每项更改都复制到此仓库中。

连接 Chrome

选项 A：日常使用的 Chrome（推荐）

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启 远程调试。随后 Chrome 会接受此计算机上程序发起的 DevTools 连接，并在每次连接前询问你。

2. 确保已登录 app.contractorforeman.net。

3. 运行：

   contractor-foreman-mcp connect
   

4. Chrome 会询问是否允许连接。点击 允许。

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，并复制两个值：_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 服务会列出每个工具及其输入架构、面向 Agent 撰写的说明和提示：读取工具会标记为只读；会向客户端发送文档的工具也会标记出来，以便客户端在运行前征求确认。

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 也会通过可流式传输的 HTTP 在 http://127.0.0.1:8787/mcp 提供 MCP，供接受 URL 的客户端使用：

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

然后可以向你的 Agent 提出如下请求：

这是 Mike 关于 Maple St 翻修项目的语音备忘。把它整理成今天的每日记录：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.")

或者从 shell 调用一个工具：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 天内到期或已经逾期的待办事项。

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 来自工具列表：project_id 来自 list_projects，invoice_id 来自 list_invoices，依此类推。运行 contractor-foreman-mcp tools 可输出此列表，运行 contractor-foreman-mcp tools --json 则会附带输入架构。此仓库包含托管版本中的所有工具。

项目、进度计划、每日日志、整改清单和待办事项（18）

工具	访问权限	REST 路由	功能
create_daily_log	写入	POST /daily-logs	为项目新建每日日志：工作记录、人员、交付情况、天气记录和延误。
create_project	写入	POST /projects	为客户新建项目，包含编号、类型、阶段、地址和日期。
create_punchlist	写入	POST /punchlists	为项目新建空白整改清单。
create_todo	写入	POST /todos	新建待办事项，可选关联项目，并设置截止日期、优先级和负责人。
get_daily_log	读取	GET /daily-logs/{daily_log_id}	查看一条每日日志：工作记录、人员和访客、材料、设备、天气和延误。
get_job_costing	读取	GET /projects/{project_id}/job-costing	查看一个项目各成本代码的估算成本和实际成本、差额及总计。
get_project	读取	GET /projects/{project_id}	查看一个项目：客户、地址、阶段、日期、合同金额、成本、开票和保留金。
get_punchlist	读取	GET /punchlists/{punchlist_id}	查看一份整改清单：项目、地址、客户，以及未完成和已完成的项目数。
get_todo	读取	GET /todos/{todo_id}	查看一项待办事项：描述、项目、优先级、状态、截止日期、负责人和检查清单。
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	列出待办事项及其项目、优先级、状态、截止日期和负责人。
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}	修改待办事项的名称、描述、截止日期、优先级或状态，例如将其标记为已完成。

估价单、变更单、发票和付款（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}	获取一份变更单或申请，包含说明、状态、总额和明细项。
get_estimate	读取	GET /estimates/{estimate_id}	获取一份估价单，包含客户、日期、条款、总额和所有明细项。
get_invoice	读取	GET /invoices/{invoice_id}	获取一张发票，包含客户、日期、条款、明细项、付款记录和应付余额。
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	写入	POST /projects/{project_id}/notes	在项目的 Notes 标签页中添加备注。
create_bill	写入	POST /bills	记录供应商账单及其明细项，可选择关联项目。
create_contact	写入	POST /contacts	在 Directory 中添加客户、员工、承包商、供应商或其他联系人。
create_expense	写入	POST /expenses	记录一笔费用（收据、采购、手续费），包括金额、日期、供应商和项目。
create_inspection	写入	POST /inspections	在项目中登记检查，包括类型、日期、机构、检查员和备注。
create_lead	写入	POST /leads	添加销售线索，包括联系人详细信息和销售阶段。
create_opportunity	写入	POST /opportunities	为客户添加销售机会，包括阶段、评分、预算和预计成交日期。
create_purchase_order	写入	POST /purchase-orders	为供应商创建采购订单草稿，包括明细项，可选择关联项目。
create_rfi	写入	POST /rfis	为项目起草信息请求，包括问题和回复截止日期。
create_service_ticket	写入	POST /service-tickets	为客户创建服务工单，可选择安排日期和时间。
create_sub_contract	写入	POST /sub-contracts	为项目创建与分包商签订的分包合同草稿。
create_work_order	写入	POST /work-orders	为项目创建状态为 Open 的工单，包括主题、描述和日期。
get_bill	读取	GET /bills/{bill_id}	获取一份供应商账单，包括明细项、日期、总额、应付余额和状态。
get_clock_status	读取	GET /clock-status	查看当前打卡上班的人员、你是否已打卡，以及本周和上周的团队工时。
get_contact	读取	GET /contacts/{contact_id}	完整获取一条 Directory 记录：联系人详细信息、状态、服务、条款和其他联系人。
get_expense	读取	GET /expenses/{expense_id}	获取一笔费用，包括金额、日期、供应商、项目、成本类型、成本代码和原因。
get_inspection	读取	GET /inspections/{inspection_id}	获取一项检查，包括类型、项目、日期、结果、机构、检查员和备注。
get_opportunity	读取	GET /opportunities/{opportunity_id}	完整获取一项销售机会：客户联系人、阶段、评分、预算、备注和最近活动。
get_purchase_order	读取	GET /purchase-orders/{purchase_order_id}	获取一份采购订单，包括供应商、日期、状态和明细项。
get_rfi	读取	GET /rfis/{rfi_id}	获取一条 RFI，包括问题、日期、答复和状态。
get_service_ticket	读取	GET /service-tickets/{service_ticket_id}	获取一张服务工单，包括客户、服务地址、日程安排、技术人员和优先级。
get_sub_contract	读取	GET /sub-contracts/{sub_contract_id}	获取一份分包合同，包括分包商、金额、保留金、工作范围和项目。
get_submittal	读取	GET /submittals/{submittal_id}	获取一份提交文件，包括图纸页、规范章节、状态、日期和其中的项目。
get_time_card	读取	GET /time-cards/{timecard_id}	获取一张工时卡或团队工时表，包括每位员工按成本代码统计的工时。
get_work_order	读取	GET /work-orders/{work_order_id}	获取一张工单，包括项目、客户、状态、日期、地点、备注和项目。
list_bills	读取	GET /bills	列出供应商账单，包括供应商、项目、日期、总额、应付余额和状态。
list_contacts	读取	GET /contacts	列出 Directory 中的客户、员工、承包商、供应商和其他联系人。
list_expenses	读取	GET /expenses	列出费用，包括金额、日期、供应商、项目、成本类型和付款人。
list_inspections	读取	GET /inspections	列出检查，包括项目、类型、日期、结果、机构和许可证编号。
list_leads	读取	GET /leads	列出销售线索，包括联系人详细信息、阶段和质量评分。
list_opportunities	读取	GET /opportunities	列出销售机会，包括客户、阶段、评分、预算和预计成交日期。
list_project_crew_hours	读取	GET /projects/{project_id}/crew-hours	列出某个项目记录的工时和人工成本，按员工、日期和成本代码统计。
list_project_files	读取	GET /projects/{project_id}/files	列出项目中的照片和文档，包括名称、大小和下载链接。
list_project_notes	读取	GET /projects/{project_id}/notes	列出项目 Notes 标签页中的备注，包括作者和时间。
list_purchase_orders	读取	GET /purchase-orders	列出采购订单，包括供应商、项目、下单日期、总额和状态。
list_rfis	读取	GET /rfis	列出信息请求，包括问题、项目、日期、答复和状态。
list_service_tickets	读取	GET /service-tickets	列出服务工单，包括客户、状态、服务日期和时间以及技术人员。
list_sub_contracts	读取	GET /sub-contracts	列出分包合同，包括分包商、项目、金额、已开票金额、已付款金额、余额和状态。
list_submittals	读取	GET /submittals	列出提交文件，包括项目、状态、收件日期、截止日期和审批人。
list_time_cards	读取	GET /time-cards	列出工时卡，包括员工或团队、项目、上班和下班打卡时间及工时，按最新时间排序。
list_work_orders	读取	GET /work-orders	列出工单，包括项目、客户、状态、日期、总额和负责人。
record_inspection_result	写入	PUT /inspections/{inspection_id}/result	将检查标记为通过、未通过或需要重新检查，可选择添加备注。
update_service_ticket_status	写入	PUT /service-tickets/{service_ticket_id}/status	将服务工单状态更新为已安排、在途中、已签到、已完成、已关闭等。
update_work_order_status	写入	PUT /work-orders/{work_order_id}/status	将工单状态更新为 open、估价中、已提交、已批准、已取消或已完成。
从未构建，且这是有意为之：您的 Contractor Foreman 登录、密码、电子邮件和双重验证设置、公司设置、订阅和账单，以及演示数据开关。每个请求都会经过一道防护机制，拒绝访问这些 Contractor Foreman 路径。

配置

变量	默认值	作用
CONTRACTOR_FOREMAN_MCP_HOME	~/.config/contractor-foreman-api-mcp	session.json 所在文件夹。
CONTRACTOR_FOREMAN_AUTH_TOKEN		会话 Cookie，格式为 _session__240322=...; auth_data_session=...，用于替代 contractor-foreman-mcp connect。
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 所需的 Bearer 令牌；要监听 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 邮件，新待办事项也会显示在受指派者的应用中。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 个
运行位置	你的电脑上，电脑开机时运行	云端，全天候运行
Contractor Foreman 会话	使用你的 Chrome，Cookie 保存在本地文件中	使用你在欧盟的专属 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 启用了供 Agent 使用的应用，每天就会消耗 50 点数。完整价格。

常见问题

Contractor Foreman 有官方 API 吗？ 没有公开的 API：没有 REST API、开发者文档或 API 密钥（截至 2026 年 10 月 11 日已核实）。唯一的程序化访问方式是 Zapier 应用，它提供 7 个用于潜在客户、客户和文件上传的触发器，以及 2 个操作：创建潜在客户和创建客户。它无法读取或写入估算、变更单、每日记录、日程安排、发票或项目成本核算。详情：cotlet.dev/integrations/contractor-foreman-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 Contractor Foreman 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。系统会自动翻页。

Agent 能帮我填写每日记录吗？ 可以。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 云浏览器中。

能在工作中或为客户使用吗？ 不可以，许可证仅允许非商业用途；即使是用它经营你自己的承包业务，也属于商业用途。团队、公司或客户项目请使用 Cotlet，或发送邮件至 [email protected]。

它是开源的吗？ 源代码是公开的，但许可证并非开源许可证：仅限非商业用途，不得用于商业活动。

某个工具出问题了，或者我需要另一个工具。 请提交问题，并注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你使用自己的 Contractor Foreman 账户满足个人需求，或慈善机构、学校、公共研究机构或政府部门使用。可以修改代码，并以相同许可证分享。
• **不允许：**任何商业用途，包括用于你自己的业务；客户项目；出售或提供该项目，或基于它构建的服务。

---

由 Cotlet（@cotletdev）维护。Contractor Foreman 是其所有者的商标。本项目为非官方项目，与 Contractor Foreman 无关，也未获其认可或赞助。