Contractor Foreman construction management for contractors MCP server: create estimate.
Model Context Protocol (MCP) Server: dev.cotlet/contractor-foreman
The MCP server “dev.cotlet/contractor-foreman” provides access to Contractor Foreman data, centered on project management. It supports working with projects, estimates, daily logs, and invoices, as reflected in its description: “Projects, estimates, daily logs and invoices in Contractor Foreman.”
🛠️ Key Features
Projects
Estimates
Daily logs
Invoices
🚀 Use Cases
Reviewing project-related information
Managing or referencing estimates
Tracking daily work logs
Accessing invoice records
⚡ Developer Benefits
Consistent organization around common contractor records (projects, estimates, daily logs, invoices)
⚠️ Limitations
Available details are limited to the server description; no additional fields (e.g., topics, toolCount, readmeExcerpt) are provided here.
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, not enabled for agents), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
Parameters1
app
string
optional
Only this app, e.g. skool.
Raw schema
{
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Only this app, e.g. skool."
}
},
"additionalProperties": false
}
cotlet_request_apps
Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
Parameters7
kind
string
required
bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.
title
string
required
One line, e.g. 'skool_list_members stops after 50 members'.
description
string
required
What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.
app
any
optional
App slug the report is about, e.g. 'skool'.
tool
any
optional
Tool or endpoint name, e.g. 'skool_list_members'.
call_id
any
optional
call_id of the call that went wrong, if any.
client
any
optional
Agent or tool sending this, e.g. 'Claude Code'.
Raw schema
{
"type": "object",
"properties": {
"kind": {
"description": "bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.",
"enum": [
"bug",
"error",
"feature_request",
"missing_feature",
"other"
],
"title": "Kind",
"type": "string"
},
"title": {
"description": "One line, e.g. 'skool_list_members stops after 50 members'.",
"maxLength": 200,
"minLength": 3,
"title": "Title",
"type": "string"
},
"description": {
"description": "What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.",
"maxLength": 5000,
"minLength": 10,
"title": "Description",
"type": "string"
},
"app": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "App slug the report is about, e.g. 'skool'.",
"title": "App"
},
"tool": {
"anyOf": [
{
"maxLength": 160,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool or endpoint name, e.g. 'skool_list_members'.",
"title": "Tool"
},
"call_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "call_id of the call that went wrong, if any.",
"title": "Call Id"
},
"client": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Agent or tool sending this, e.g. 'Claude Code'.",
"title": "Client"
}
},
"required": [
"kind",
"title",
"description"
],
"additionalProperties": false,
"description": "Body of POST /api/v1/reports and the arguments of the MCP tool cotlet_report_issue.",
"title": "AgentReportCreate"
}
cotlet_browser_connect
Wakes the user's Cloud Browser of one app (a real Chrome on Cotlet, signed in to that app as the user) and returns cdp_url, a Chrome DevTools Protocol WebSocket that gives a CDP client full control of the browser. It works in one open tab, the app's: the user watches it live, and new tabs are refused. Every started minute of an open connection costs credits. Needs the user's Cotlet API key or sign-in.
Open Chrome DevTools connections to the user's Cloud Browsers with the minutes and credits each has cost so far, and the cdp_url links still valid. With close: true it ends the open connections and takes back the unused links, of one app or of all. Needs the user's Cotlet API key or sign-in.
Parameters1
close
boolean
optional
End the connections and revoke the links.
Raw schema
{
"type": "object",
"properties": {
"close": {
"type": "boolean",
"description": "End the connections and revoke the links."
}
},
"additionalProperties": false
}
cotlet_browser_open
Wakes the user's own browser on Cotlet, a real Chrome hosted for them: their web browser with the sites they signed in to there, or with `app` that app's browser, signed in to the app. Opens `url` when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
optional
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"additionalProperties": false
}
cotlet_browser_navigate
Opens a public http or https address in the user's browser on Cotlet and returns the URL and title it ended on. An app's browser opens only that app's pages. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
required
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"required": [
"url"
],
"additionalProperties": false
}
cotlet_browser_read
Returns the current page of the user's browser on Cotlet: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Returns a JPEG image of the visible part of the current page in the user's browser on Cotlet, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Scrolls the current page in the user's browser on Cotlet with the mouse wheel, as a person does: down or up by `screens` viewport heights (default 0.8), to the top or the bottom, or until element `element` is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
direction
string
optional
Where to scroll. Default: down.
screens
number
optional
How far, in viewport heights, for down and up. Default: 0.8.
element
integer
optional
Scroll until this element of the element list is in view.
Raw schema
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"enum": [
"down",
"up",
"top",
"bottom"
],
"description": "Where to scroll. Default: down."
},
"screens": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 10,
"description": "How far, in viewport heights, for down and up. Default: 0.8."
},
"element": {
"type": "integer",
"minimum": 1,
"description": "Scroll until this element of the element list is in view."
}
},
"additionalProperties": false
}
cotlet_browser_click
Clicks a link, button or other element of the current page in the user's browser on Cotlet, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
element
integer
required
The element's number in the element list of the current page.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
}
},
"required": [
"element"
],
"additionalProperties": false
}
cotlet_browser_type
Types text into a field of the current page in the user's browser on Cotlet, by the field's number in the page's element list, and with `submit` presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
element
integer
required
The element's number in the element list of the current page.
text
string
required
The text to type.
submit
boolean
optional
Press Enter after typing, e.g. to search.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"text": {
"type": "string",
"maxLength": 5000,
"description": "The text to type."
},
"submit": {
"type": "boolean",
"description": "Press Enter after typing, e.g. to search."
}
},
"required": [
"element",
"text"
],
"additionalProperties": false
}
cotlet_browser_select
Chooses an option of a drop-down list on the current page in the user's browser on Cotlet, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
option
string
required
The option.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"option": {
"type": "string",
"maxLength": 300,
"description": "The option."
}
},
"required": [
"element",
"option"
],
"additionalProperties": false
}
cotlet_browser_press
Presses one key on the current page in the user's browser on Cotlet, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Puts files into a file field of the current page in the user's browser on Cotlet, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
files
array
required
The files.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public file URL."
},
"file_id": {
"type": "string",
"description": "A file uploaded to Cotlet."
}
},
"additionalProperties": false
},
"description": "The files."
}
},
"required": [
"element",
"files"
],
"additionalProperties": false
}
cotlet_browser_close
Ends the session in the user's browser on Cotlet (with `app`, that app's browser): the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
Contractor Foreman API and MCP server: connect Contractor Foreman to ChatGPT and Claude
Yes, ChatGPT, Claude and other AI agents can work in your Contractor Foreman account. That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI writes estimates, logs daily reports, updates the schedule, creates invoices and reports job costs. It shows you what it will do first and sends nothing to other people until you say so.
As of November 2026, this repo is the missing piece: 89 Contractor Foreman tools for AI assistants and scripts.
What you can ask
Here is Mike's voice note from the Maple St remodel. Turn it into today's daily log: framing crew of 4, one electrician, drywall delivered, rain stopped work at 2:30.
Turn this scope list from the Johnson bathroom walkthrough into an estimate with 20% markup on materials, show me the total, then email it to the client.
Which open projects have cost codes running over the estimate? Show the biggest overruns first.
List overdue invoices with the balance and days late, then record the $1,200 check from Burger Palace against invoice 11.
sign in to Contractor Foreman once, about 5 minutes, nothing to install
Python and a terminal
Works in
ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST API
Claude Code, Claude Desktop, Cursor, Codex on your computer
Runs
24/7, your computer can be off
while your computer is on
Price
7 days free, no card
free
Cotlet is best for contractors, builders and project managers who want ChatGPT, Claude or another AI agent to work in Contractor Foreman for them, with nothing to install.
A Contractor Foreman API and a Contractor Foreman MCP server you run on your own computer, in Python, on the session of your own Google Chrome. All 89 Contractor Foreman tools we run in production at Cotlet: projects, schedule, daily logs, punchlists, to-dos, estimates, change orders, invoices, payments, job costing, directory, leads, time cards, bills, purchase orders, sub-contracts, work orders, service tickets, RFIs, submittals and inspections.
Contractor Foreman has no public API and no official MCP server. This repo gives you both:
MCP server for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. Setup
REST API on http://127.0.0.1:8787/api/v1/contractor-foreman, with OpenAPI docs at /docs. Setup
Python: call("list_projects", search="Oak St"), plus 10 ready scripts in examples/.
Free for your own use, your own business included (license).
Does Contractor Foreman have an API?
No public one: no REST API, developer docs or API keys (checked 11 Oct 2026). The only programmatic access is a Zapier app with 7 triggers for leads, customers and file uploads, and 2 actions, Create Lead and Create Customer. It cannot read or write estimates, change orders, daily logs, the schedule, invoices or job costing. This repo and Cotlet give you 89 Contractor Foreman tools as a REST API and an MCP server.
Can I get a Contractor Foreman API key?
Not from Contractor Foreman for your own account. With Cotlet you get your own API key that works with your Contractor Foreman account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own Contractor Foreman session.
Is there an official ChatGPT integration for Contractor Foreman?
No. Contractor Foreman has no official ChatGPT or Claude connector. Cotlet is an unofficial one that works today, in the ChatGPT and Claude apps and in any AI agent that takes an MCP server.
How do I connect Contractor Foreman to ChatGPT?
Sign up at cotlet.dev, sign in to Contractor Foreman once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your Contractor Foreman like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
Can ChatGPT create estimates and daily logs in Contractor Foreman?
Yes, with Cotlet. It writes estimates and change orders, logs daily reports from your notes, updates the schedule and creates invoices. You approve every change.
Can I get Contractor Foreman data into a spreadsheet?
Yes, with Cotlet: projects, estimates, invoices and daily logs, as answers in chat or JSON for your sheet.
Can I automate Contractor Foreman with Zapier, Make or n8n?
Contractor Foreman's Zapier app has triggers for leads, customers and files and two actions, Create Lead and Create Customer. With Cotlet, n8n, Make and Zapier can also work with estimates, daily logs, the schedule and invoices.
Can I use it from my phone?
Yes, with Cotlet: once it is set up, the ChatGPT and Claude apps on your phone can use Contractor Foreman for you.
Do I need to be technical?
For Cotlet, no: you sign in to Contractor Foreman and add Cotlet to ChatGPT or Claude, with step-by-step instructions in your account. This repo is for people who are fine with Python and a terminal.
Is my Contractor Foreman account safe?
Yes. Neither Cotlet nor this repo sees or stores your Contractor Foreman password. You sign in yourself, the way you always do, and the AI works on that signed-in session. Anything that reaches other people asks for your OK first: in Cotlet by default, here through your MCP client.
Is it free?
This repo is free, also in your own business. Cotlet is free for 7 days with no card, then one-time credit packs from $29, no subscription. Pricing.
I manage Contractor Foreman for several accounts or clients. Does that work?
Yes, with Cotlet. Each Contractor Foreman login gets its own connection. Write to contact@cotlet.dev and tell us how many accounts you manage.
How it works
text
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)
You sign in to Contractor Foreman in your own Chrome, the way you always do.
contractor-foreman-mcp connect attaches to that Chrome through the Chrome DevTools Protocol, reads the contractorforeman.net cookies and your browser's time zone, and saves them to ~/.config/contractor-foreman-api-mcp/session.json, readable by your user only. It never sees or stores your password.
Every tool call is a request to the same /api/... endpoints the Contractor Foreman web app calls, with those cookies, sent with curl_cffi, which copies Chrome's TLS fingerprint. No browser runs for a call.
Contractor Foreman answers a signed-out request with HTTP 200 and a "signed out" body, and the tools turn that into auth_expired. The server then reads the cookies from Chrome again, if Chrome is open with remote debugging on. Times you send are saved in the time zone connect read from Chrome.
Requirements
Python 3.11 or newer.
Google Chrome 144 or newer, signed in to Contractor Foreman. Any Chrome or Chromium works with a debugging port.
macOS, Linux or Windows.
A Contractor Foreman role with access to the modules you use. A tool on a module your role cannot open fails with the app's own message.
With uv: uv venv && uv pip install -e ., then uv run contractor-foreman-mcp ....
Setting it up with an AI agent (Claude Code, Codex, Cursor)? Open it in this folder and ask it to set up the repo: AGENTS.md tells it every step, and it asks you only for the steps in Chrome.
To update: uv tool upgrade contractor-foreman-api-mcp (or pip install -U contractor-foreman-api-mcp), from source git pull && pip install -e .. We copy every change of the hosted Contractor Foreman tools into this repo.
Connect your Chrome
Option A: your everyday Chrome (recommended)
Open chrome://inspect/#remote-debugging in Chrome and switch remote debugging on. Chrome then accepts DevTools connections from programs on this computer, and asks you before each one.
Chrome asks whether to allow the connection. Click Allow.
text
Saved 34 Contractor Foreman cookies to /Users/you/.config/contractor-foreman-api-mcp/session.json
Signed in to Contractor Foreman as Mike Turner (mike@turnerbuilds.com)
You can switch remote debugging off again afterwards. Leave it on if you want the server to pick up a new session by itself after Contractor Foreman signs you out.
connect looks for Chrome's DevToolsActivePort file in the default profile folder. For Chrome Beta, Canary or a custom profile folder, pass --profile-dir "<folder>".
Option B: a Chrome with a debugging port
Chrome does not open a debugging port on your default profile, so start a separate one, sign in to Contractor Foreman there once, and connect to it:
--cdp also takes a ws:// DevTools URL, for example of a Chrome on another machine reached over an SSH tunnel.
Option C: paste the cookies by hand
For a server with no Chrome: in Chrome open DevTools on app.contractorforeman.net, Application > Cookies, and copy two values: _session__240322 (under https://app.contractorforeman.net) and auth_data_session (under .contractorforeman.net). Then:
bash
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=...'
Pasted cookies are not refreshed on their own. Paste new ones when Contractor Foreman signs you out. Without Chrome the time zone is this machine's (TZ or the system setting).
Check the session at any time:
bash
contractor-foreman-mcp status
MCP server
The MCP server lists every tool with its input schema, a description written for agents, and hints: read tools are marked read-only, and tools that email documents to clients are marked so your client asks before running them.
Claude Code
bash
claude mcp add contractor-foreman -- uvx contractor-foreman-api-mcp mcp
# read only:
claude mcp add contractor-foreman -- uvx contractor-foreman-api-mcp mcp --read-only
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
contractor-foreman-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:
bash
contractor-foreman-mcp serve
claude mcp add --transport http contractor-foreman http://127.0.0.1:8787/mcp
Then ask your agent things like:
Here is Mike's voice note from the Maple St remodel. Turn it into today's daily log: framing crew of 4, one electrician, drywall delivered, rain stopped work at 2:30.
Turn this scope list from the Johnson bathroom walkthrough into an estimate with 20% markup on materials, show me the total, then email it to the client.
Which open projects have cost codes running over the estimate? Show the biggest overruns first.
List overdue invoices with the balance and days late, then record the $1,200 check from Burger Palace against invoice 11.
REST API
bash
contractor-foreman-mcp serve # http://127.0.0.1:8787, MCP at /mcp, docs at /docs
Each tool has its own route under /api/v1/contractor-foreman, the same paths as the hosted API at cotlet.dev, so code written against one works with the other. Path parts and the query string are arguments, and a JSON body adds the rest.
bash
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}}'
Any tool by name, body as its arguments:
bash
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: every tool with its route, input schema and an example answer.
GET /docs: interactive OpenAPI docs, GET /openapi.json the schema, for n8n, Postman or a generated client.
Answers are JSON. Lists return next_cursor; pass it back as cursor for the next page.
The server listens on 127.0.0.1 only. To reach it from another device of yours, set a token, and every request then needs Authorization: Bearer <token>:
Open to-dos due in the next N days or already late, by project.
bash
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
On a schedule, cron on your own computer works while it is on: 0 8 * * 1 cd ~/contractor-foreman-api-mcp-server && .venv/bin/python examples/overdue_invoices.py --out overdue.csv.
All 89 tools
Ids come from the list tools: project_id from list_projects, invoice_id from list_invoices and so on. contractor-foreman-mcp tools prints this list, contractor-foreman-mcp tools --json adds the input schemas. Every tool of the hosted version is in this repo.
Projects, schedule, daily logs, punchlists and to-dos (18)
Tool
Access
REST route
What it does
create_daily_log
write
POST /daily-logs
New daily log on a project: work notes, people, deliveries, weather notes and delays.
create_project
write
POST /projects
New project for a customer, with number, type, stage, address and dates.
create_punchlist
write
POST /punchlists
New, empty punchlist on a project.
create_todo
write
POST /todos
New to-do, optionally on a project, with due date, priority and assignees.
get_daily_log
read
GET /daily-logs/{daily_log_id}
One daily log: work notes, people and visitors, materials, equipment, weather and delays.
get_job_costing
read
GET /projects/{project_id}/job-costing
Estimated and actual cost per cost code for one project, with the difference and totals.
get_project
read
GET /projects/{project_id}
One project: customer, address, stage, dates, contract amounts, costs, billing and retainage.
get_punchlist
read
GET /punchlists/{punchlist_id}
One punchlist: project, address, customer and how many items are open and completed.
get_todo
read
GET /todos/{todo_id}
One to-do: description, project, priority, status, due date, assignees and checklist.
list_daily_logs
read
GET /daily-logs
Daily logs by date, optionally for one project and a date range.
list_projects
read
GET /projects
Projects with customer, stage, dates, contract amount, costs and percent complete.
list_punchlists
read
GET /punchlists
Punchlists with project, status, open and completed item counts and who the items are assigned to.
list_schedule_tasks
read
GET /projects/{project_id}/schedule-tasks
Gantt schedule tasks of a project: dates, duration, dependencies, assignees, percent complete.
list_todos
read
GET /todos
To-dos with project, priority, status, due date and assignees.
update_daily_log
write
PATCH /daily-logs/{daily_log_id}
Change the notes, times, people, deliveries, weather notes or delays of a daily log.
update_project
write
PATCH /projects/{project_id}
Change a project's name, stage, type, address, dates or description.
Change the name, dates, length or percent complete of a task on the project schedule.
update_todo
write
PATCH /todos/{todo_id}
Change a to-do's name, description, due date, priority or status, e.g. mark it complete.
Estimates, change orders, invoices and payments (27)
Tool
Access
REST route
What it does
add_change_order_items
write
POST /change-orders/{change_order_id}/items
Adds priced line items to a change order or change order request.
add_estimate_items
write
POST /estimates/{estimate_id}/items
Adds priced line items to an existing estimate.
add_invoice_items
write
POST /invoices/{invoice_id}/items
Adds priced line items to an invoice.
create_change_order
write
POST /change-orders
Creates a change order or change order request on a project, with line items.
create_estimate
write
POST /estimates
Creates a draft estimate on a project or for a customer, with priced line items.
create_invoice
write
POST /invoices
Creates a draft invoice for a project or customer, with priced line items.
create_share_link
write
POST /share-links
Makes a short internal link that opens an estimate, change order or invoice for your signed-in team.
delete_change_order
write
DELETE /change-orders/{change_order_id}
Deletes a change order or change order request for good.
delete_estimate
write
DELETE /estimates/{estimate_id}
Deletes an estimate for good.
delete_invoice
write
DELETE /invoices/{invoice_id}
Deletes an invoice that has no payments, for good.
get_change_order
read
GET /change-orders/{change_order_id}
One change order or request with description, status, total and line items.
get_estimate
read
GET /estimates/{estimate_id}
One estimate with customer, dates, terms, totals and every line item.
get_invoice
read
GET /invoices/{invoice_id}
One invoice with customer, dates, terms, line items, payments and balance due.
list_change_orders
read
GET /change-orders
Change orders and change order requests, newest first, with status, project and total.
list_cost_codes
read
GET /cost-codes
The company's cost codes, to put on estimate, change order and invoice items.
list_cost_items
read
GET /cost-items
Saved cost items with unit, unit cost and markup, to price estimate and change order lines.
list_estimates
read
GET /estimates
Estimates, newest first, with status, project, customer and total.
list_invoices
read
GET /invoices
Invoices, newest first, with status, totals, balance due and an overdue flag.
list_payments
read
GET /payments
Payments received on invoices, newest first, with amount, method and invoice.
record_payment
write
POST /invoices/{invoice_id}/payments
Records a payment you received against an invoice.
remove_estimate_items
write
DELETE /estimates/{estimate_id}/items
Deletes line items from an estimate.
send_change_order
write
POST /change-orders/{change_order_id}/send
Emails the change order as a PDF to the customer or to the addresses you give.
send_estimate
write
POST /estimates/{estimate_id}/send
Emails the estimate as a PDF to the customer or to the addresses you give.
send_invoice
write
POST /invoices/{invoice_id}/send
Emails the invoice as a PDF to the customer or to the addresses you give.
update_change_order
write
PATCH /change-orders/{change_order_id}
Changes a change order's status, title, reason or date.
update_estimate
write
PATCH /estimates/{estimate_id}
Changes an estimate's status, title, dates, description, inclusions or exclusions.
update_invoice
write
PATCH /invoices/{invoice_id}
Changes an invoice's status, invoice date, due date or description.
Directory, leads, time cards, purchasing and field work (44)
Tool
Access
REST route
What it does
add_project_note
write
POST /projects/{project_id}/notes
Adds a note to a project's Notes tab.
create_bill
write
POST /bills
Records a vendor bill with its line items, optionally against a project.
create_contact
write
POST /contacts
Adds a customer, employee, contractor, vendor or misc contact to the Directory.
create_expense
write
POST /expenses
Records an expense (receipt, purchase, fee) with amount, date, vendor and project.
create_inspection
write
POST /inspections
Logs an inspection on a project with type, date, agency, inspector and notes.
create_lead
write
POST /leads
Adds a sales lead with contact details and a pipeline stage.
create_opportunity
write
POST /opportunities
Adds a sales opportunity for a customer with stage, score, budget and expected sale date.
create_purchase_order
write
POST /purchase-orders
Creates a draft purchase order to a supplier with line items, optionally for a project.
create_rfi
write
POST /rfis
Drafts a request for information on a project, with the question and a reply-by date.
create_service_ticket
write
POST /service-tickets
Opens a service ticket for a customer, optionally scheduled for a date and time.
create_sub_contract
write
POST /sub-contracts
Creates a draft sub-contract with a subcontractor on a project.
create_work_order
write
POST /work-orders
Creates an Open work order on a project with subject, description and dates.
get_bill
read
GET /bills/{bill_id}
One vendor bill with its line items, dates, total, balance due and status.
get_clock_status
read
GET /clock-status
Who is clocked in right now, whether you are, and this and last week's crew hours.
get_contact
read
GET /contacts/{contact_id}
One Directory record in full: contact details, status, services, terms and additional contacts.
get_expense
read
GET /expenses/{expense_id}
One expense with amount, date, vendor, project, cost type, cost code and reason.
get_inspection
read
GET /inspections/{inspection_id}
One inspection with type, project, date, result, agency, inspector and notes.
get_opportunity
read
GET /opportunities/{opportunity_id}
One opportunity in full: customer contact, stage, score, budget, notes and last activity.
get_purchase_order
read
GET /purchase-orders/{purchase_order_id}
One purchase order with supplier, dates, status and its line items.
get_rfi
read
GET /rfis/{rfi_id}
One RFI with its question, dates, answer and status.
get_service_ticket
read
GET /service-tickets/{service_ticket_id}
One service ticket with customer, service address, schedule, technicians and priority.
get_sub_contract
read
GET /sub-contracts/{sub_contract_id}
One sub-contract with subcontractor, amounts, retainage, scope of work and items.
get_submittal
read
GET /submittals/{submittal_id}
One submittal with plan sheet, specification section, status, dates and its items.
get_time_card
read
GET /time-cards/{timecard_id}
One time card or crew sheet with hours per employee and cost code.
get_work_order
read
GET /work-orders/{work_order_id}
One work order with project, customer, status, dates, location, notes and items.
list_bills
read
GET /bills
Vendor bills with vendor, project, dates, total, balance due and status.
list_contacts
read
GET /contacts
Customers, employees, contractors, vendors and misc contacts from the Directory.
list_expenses
read
GET /expenses
Expenses with amount, date, vendor, project, cost type and who paid.
list_inspections
read
GET /inspections
Inspections with project, type, date, result, agency and permit number.
list_leads
read
GET /leads
Sales leads with contact details, stage and quality score.
list_opportunities
read
GET /opportunities
Sales opportunities with customer, stage, score, budget and expected sale date.
list_project_crew_hours
read
GET /projects/{project_id}/crew-hours
Hours and labor cost logged on one project, per employee and per day and cost code.
list_project_files
read
GET /projects/{project_id}/files
Photos and documents on a project, with name, size and a download link.
list_project_notes
read
GET /projects/{project_id}/notes
The notes on a project's Notes tab, with author and time.
list_purchase_orders
read
GET /purchase-orders
Purchase orders with supplier, project, order date, total and status.
list_rfis
read
GET /rfis
Requests for information with question, project, dates, answer and status.
list_service_tickets
read
GET /service-tickets
Service tickets with customer, status, service date and time and technicians.
list_sub_contracts
read
GET /sub-contracts
Sub-contracts with subcontractor, project, amount, billed, paid, balance and status.
list_submittals
read
GET /submittals
Submittals with project, status, date received, due date and approver.
list_time_cards
read
GET /time-cards
Time cards with employee or crew, project, clock-in and clock-out times and hours, newest first.
list_work_orders
read
GET /work-orders
Work orders with project, customer, status, dates, total and assignee.
record_inspection_result
write
PUT /inspections/{inspection_id}/result
Marks an inspection passed, failed or to re-inspect, optionally with notes.
update_service_ticket_status
write
PUT /service-tickets/{service_ticket_id}/status
Moves a service ticket to scheduled, en route, checked in, completed, closed and so on.
update_work_order_status
write
PUT /work-orders/{work_order_id}/status
Moves a work order to open, estimating, submitted, approved, canceled or completed.
Never built, on purpose: your Contractor Foreman sign-in, password, email and two-factor settings, company settings, the subscription and billing, and the demo data switch. Every request passes a guard that refuses those Contractor Foreman paths.
Configuration
Variable
Default
What it does
CONTRACTOR_FOREMAN_MCP_HOME
~/.config/contractor-foreman-api-mcp
Folder of session.json.
CONTRACTOR_FOREMAN_AUTH_TOKEN
The session cookies as _session__240322=...; auth_data_session=..., instead of contractor-foreman-mcp connect.
CONTRACTOR_FOREMAN_PROXY
Proxy for every request to Contractor Foreman, e.g. http://user:pass@host:port.
CONTRACTOR_FOREMAN_MCP_READ_ONLY
1 hides and refuses every tool that changes Contractor Foreman (same as --read-only).
CONTRACTOR_FOREMAN_MCP_TOKEN
Bearer token required by serve; needed to listen beyond 127.0.0.1.
Your password never reaches this code. Only cookies are read, and only those of contractorforeman.net.
The session file is yours.session.json is created with mode 0600. Anyone who has it can act as you in Contractor Foreman, so keep it out of git and shared folders.
Local by default.serve binds to 127.0.0.1 and refuses another address without CONTRACTOR_FOREMAN_MCP_TOKEN.
contractorforeman.net only. Requests and redirects to other hosts are refused.
Read-only mode.--read-only or CONTRACTOR_FOREMAN_MCP_READ_ONLY=1 exposes the 48 read tools only.
Some actions reach clients.send_estimate, send_change_order and send_invoice email a PDF from your account, and a new to-do shows up in its assignees' app. MCP clients ask before running them. A script does not, so try it on a test project first.
Deletes are final.delete_estimate, delete_change_order and delete_invoice remove the record as the app's own delete does.
Errors
The REST API answers {"error": "<code>", "message": "..."}. The MCP server returns the same code and message as a tool error.
Status
Code
What to do
401
auth_required, auth_expired
No session, or Contractor Foreman signed you out. Sign in in Chrome and run contractor-foreman-mcp connect.
403
app_permission_denied
Your Contractor Foreman role cannot open that module.
403
scope_denied
The server runs read-only, or the request would change account settings or billing.
403
target_blocked
Contractor Foreman refused the request or showed a bot check. Open the app in Chrome once, then retry.
409
captcha_required
Contractor Foreman asks for a CAPTCHA. Solve it in Chrome.
422
invalid_input
An argument is missing or wrong; the message names it.
429
rate_limited
Contractor Foreman is limiting the account. Wait a few minutes.
502
target_error
Contractor Foreman answered with an error (the message quotes it), or changed its app. git pull for the latest tools, or open an issue.
your own Cloud Browser in the EU, profile encrypted with AES-256-GCM
When Contractor Foreman changes its app
git pull once we have fixed it
fixed for you, every tool tested daily
Approvals
your MCP client asks per call
emails to clients wait for your OK, switchable per tool
Works with
MCP clients on your machine, local scripts
Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client
Who may use it
you and your own business
you, teams, businesses, agencies
Price
free
free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits
On the hosted version a successful call uses 10 credits, failed calls are free, and the Cloud Browser uses 50 credits a day while it has an app enabled for agents. Full pricing.
FAQ
Is there a Contractor Foreman MCP server for Claude, ChatGPT or Cursor?
Yes, this one runs on your machine: contractor-foreman-mcp mcp for Claude Code, Claude Desktop, Cursor and Codex. ChatGPT and Claude.ai connectors need a public HTTPS URL, which the hosted Contractor Foreman MCP server gives you.
Is this a scraper?
It does what people want a scraper for (export projects, invoices and time cards to CSV) but parses no HTML. It calls the same JSON endpoints the Contractor Foreman web app calls, in your own account.
Can I export projects, invoices or crew hours to CSV?
Yes: python examples/export_projects.py --out projects.csv, python examples/overdue_invoices.py --out overdue.csv or python examples/crew_hours.py --days 30 --out hours.csv. Pages are followed automatically.
Can an agent write my daily logs?
Yes. create_daily_log takes the notes, crews with headcounts, deliveries and weather remarks. Contractor Foreman records the weather for the date and address itself. examples/add_daily_log.py first checks that the day has no log yet.
Why does it need my Chrome?
To read your Contractor Foreman session without your password. Chrome is used once per sign-in, not for each call.
What happens when Contractor Foreman signs me out?
Calls fail with auth_expired. With Chrome remote debugging on, the server reads the new cookies on the next call (click Allow when Chrome asks). Otherwise run contractor-foreman-mcp connect again.
Can it run on a VPS or in Docker?
Technically yes, with CONTRACTOR_FOREMAN_AUTH_TOKEN. Contractor Foreman then sees your session from a datacenter IP, which looks less like you. For an always-on setup the hosted version keeps your session in your own Cloud Browser on a fixed IP.
Can I use it at work or for my clients?
At work and in your own business, yes, free. You may not offer it to others as a hosted or managed service. For client work, use Cotlet or write to contact@cotlet.dev.
Is it open source?
The source is public under the Elastic License 2.0: free to use and change, also in your own business, but not to resell as a hosted service.
A tool broke or I need another one.Open an issue with the tool name and the error message.
Allowed: using it for yourself and in your own business, free. Changing the code and sharing it under the same license.
Not allowed: offering it to others as a hosted or managed service, removing the license notices, getting around its limits.
Maintained by Cotlet (@cotletdev). Contractor Foreman is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by Contractor Foreman.