Skip to main content
Glama
Contractor Foreman MCP Server

Contractor Foreman MCP Server

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.

Related MCP server: Tradify MCP server

Two ways to get it

Ready to use, at Cotlet

Run it yourself, this repo

For

contractors, builders and project managers

developers

Setup

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.

Start free at cotlet.dev →

Run it yourself

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).

Contractor Foreman MCP server Python 3.11+ License: Elastic 2.0 MCP Badge

Also on Odel: https://odel.app/modules/cotlet/contractor-foreman and mcpbeat: https://mcpbeat.com/mcp-servers/cotlet/contractor-foreman/

uv tool install contractor-foreman-api-mcp                  # or: pip install contractor-foreman-api-mcp
contractor-foreman-mcp connect                     # reads your Contractor Foreman session from Chrome
contractor-foreman-mcp call list_projects
claude mcp add contractor-foreman -- uvx contractor-foreman-api-mcp mcp

Contents

Questions from Contractor Foreman users

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

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. You sign in to Contractor Foreman in your own Chrome, the way you always do.

  2. 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.

  3. 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.

Install

From PyPI:

uv tool install contractor-foreman-api-mcp       # or: pipx install contractor-foreman-api-mcp, or: pip install contractor-foreman-api-mcp
contractor-foreman-mcp --version

MCP clients can also run it with no install: uvx contractor-foreman-api-mcp mcp.

From source:

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

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

  1. 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.

  2. Make sure you are signed in at app.contractorforeman.net.

  3. Run:

    contractor-foreman-mcp connect
  4. Chrome asks whether to allow the connection. Click Allow.

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:

# 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 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:

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:

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

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):

{
  "mcpServers": {
    "contractor-foreman": {
      "command": "uvx",
      "args": ["contractor-foreman-api-mcp", "mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json, the same block as Claude Desktop. A ready copy is in mcp.json.

Codex

~/.codex/config.toml:

[mcp_servers.contractor-foreman]
command = "uvx"
args = ["contractor-foreman-api-mcp", "mcp"]

Over HTTP

contractor-foreman-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:

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

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.

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:

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>:

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

Python and the example scripts

Straight from Python, no server needed:

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.")

Or one tool from the shell: contractor-foreman-mcp call list_invoices unpaid_only=true limit=10, or with a JSON object.

Ready scripts in examples/. Each prints JSON or a short report, takes --out file.csv or --out file.json where it makes sense, and --help:

Script

What it does

export_projects.py

Projects to CSV or JSON: customer, stage, dates, contract amount, costs, percent complete. --status, --search.

add_daily_log.py

A daily log from a site note, crews and deliveries, after checking the day has no log yet. --dry-run.

create_estimate.py

An estimate from a scope list in CSV with markup. Prints the total, --send emails the PDF.

create_change_order.py

A change order or change order request from a client request; --send emails a saved one.

reschedule_task.py

Moves a schedule task by N days and every task that depends on it. --dry-run.

over_budget_projects.py

Cost codes of open projects whose actual cost runs past the estimate, biggest overrun first.

overdue_invoices.py

Past-due invoices with a balance, oldest first, with days overdue and the total outstanding.

record_payment.py

Records a check or transfer against an invoice found by its number, prints the new balance.

crew_hours.py

Hours and labor cost per project and employee from time cards, for the last N days or a date range.

open_todos.py

Open to-dos due in the next N days or already late, by project.

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.

update_schedule_task

write

PATCH /projects/{project_id}/schedule-tasks/{task_id}

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.

CONTRACTOR_FOREMAN_MCP_HOST, CONTRACTOR_FOREMAN_MCP_PORT

127.0.0.1, 8787

Address of serve.

Security and your Contractor Foreman account

  • 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.

Self-hosted or hosted

This repo

Cotlet, hosted

Tools

the same 89

the same 89

Runs

on your computer, while it is on

in the cloud, 24/7

Contractor Foreman session

your Chrome, cookies in a local file

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.

License

Elastic License 2.0. In short:

  • 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.

Available Tools

89 tools
add_change_order_itemsAdd change order itemsAInspect

Adds priced line items to a change order or change order request.

Adds line items at the end of the change order's first section: name, type (material, labor, equipment, subcontractor, other), quantity, unit, unit cost in dollars and markup percent. The app computes totals. Returns the saved items and the new total.

Inputs: items (required), change_order_id (required).

add_estimate_itemsAdd estimate itemsAInspect

Adds priced line items to an existing estimate.

Adds line items at the end of an estimate section (the first one unless section_id says otherwise). Each item has a name, a type (material, labor, equipment, subcontractor, other), quantity, unit, your unit cost in dollars and a markup percent. Contractor Foreman computes the totals. cost_code_id comes from list_cost_codes. Returns the saved items and the new estimate total.

Inputs: items (required), estimate_id (required), section_id.

add_invoice_itemsAdd invoice itemsAInspect

Adds priced line items to an invoice.

Adds plain priced lines at the end of an invoice: name, type, quantity, unit, unit cost in dollars, markup percent. Items billed from an estimate, change order or schedule of values are added in the app. Returns the saved items, the new total and the balance due.

Inputs: items (required), invoice_id (required).

add_project_noteAdd project noteBInspect

Adds a note to a project's Notes tab.

Writes a note on a Contractor Foreman project's Notes tab as the signed-in user, with an optional title. It is visible to the company's users with access to the project. Nobody is notified. Returns the saved note.

Inputs: text (required), project_id (required), title.

create_billCreate billAInspect

Records a vendor bill with its line items, optionally against a project.

Enters a bill from a vendor in Contractor Foreman: the vendor's invoice number, bill and due date, subject, notes and line items (description, quantity, unit, unit cost, cost type). With a project_id the cost shows in that project's job costing. The bill starts Open and nothing is paid or sent. Returns the saved bill.

Inputs: items (required), number (required), vendor_id (required), notes, +4 more.

create_change_orderCreate change orderAInspect

Creates a change order or change order request on a project, with line items.

Saves a new change order (status open) or change order request (status draft) on a project, for the project's customer. description records the reason. items are priced lines (name, type, quantity, unit, unit cost in dollars, markup percent, cost code). The app computes the total. Nothing is sent. send_change_order emails it after your OK, update_change_order sets the status.

Inputs: title (required), project_id (required), date, kind, +3 more.

create_contactCreate contactAInspect

Adds a customer, employee, contractor, vendor or misc contact to the Directory.

Creates a Contractor Foreman Directory record as the Add drawer does. Employees need a first and last name, contractors and vendors a company name, the others a name or a company. The record gets no app access and nobody is invited or emailed. Giving an employee a login stays a step in the app. Returns the new contact_id.

Inputs: type (required), zip, cell, city, +8 more.

create_daily_logCreate daily logAInspect

New daily log on a project: work notes, people, deliveries, weather notes and delays.

Adds a daily log to the project for the date you give (arrival 07:00 unless you say otherwise) and returns it as get_daily_log shows it. Contractor Foreman records the weather for the date and the project address itself, and weather_notes sits next to it. notes must not be empty. people takes a headcount per crew or free text. The log reaches no client or crew and update_daily_log can edit it, so this tool runs without asking. One project can have several logs on one date: check list_daily_logs first.

Inputs: date (required), notes (required), project_id (required), people, +8 more.

create_estimateCreate estimateAInspect

Creates a draft estimate on a project or for a customer, with priced line items.

Saves a new estimate in the Estimating status, unit-price billing, dated today. With project_id it belongs to that project and its customer. Without one, customer_id is required. items are priced lines (name, type, quantity, unit, unit cost in dollars, markup percent, cost code). The app computes totals. Nothing is sent: send_estimate does that after your OK. More lines later with add_estimate_items, other fields with update_estimate.

Inputs: title (required), items, exclusions, inclusions, +4 more.

create_expenseCreate expenseAInspect

Records an expense (receipt, purchase, fee) with amount, date, vendor and project.

Enters an expense in Contractor Foreman as the signed-in user: name, amount, date, vendor, project, cost type, reason and whether it is billable to the customer. The project is required by the app, and the expense shows in that project's job costing. No receipt file is attached. Returns the saved expense.

Inputs: name (required), amount (required), project_id (required), date, +4 more.

create_inspectionCreate inspectionAInspect

Logs an inspection on a project with type, date, agency, inspector and notes.

Creates a Contractor Foreman inspection in Draft status on a project: inspection type, day, agency (internal, county, city or independent agency), inspector and notes. record_inspection_result sets pass, fail or re-inspect afterwards. Nobody is notified. Returns the saved inspection.

Inputs: type (required), project_id (required), date, notes, +2 more.

create_invoiceCreate invoiceAInspect

Creates a draft invoice for a project or customer, with priced line items.

Saves a new invoice in the Draft status. With project_id it bills that project's customer. Without one, customer_id is required. A description needs due_date in the same call. items are plain priced lines (name, type, quantity, unit, unit cost in dollars, markup percent). It is not sent. update_invoice with status submitted marks it sent and lets record_payment take payments. send_invoice emails it after your OK.

Inputs: items, number, due_date, project_id, +3 more.

create_leadCreate leadAInspect

Adds a sales lead with contact details and a pipeline stage.

Creates a lead in the Contractor Foreman Directory as the Leads Add drawer does: a name or a company, contact details, address and the stage (received by default). Nobody is emailed. Returns the new contact_id, which list_leads and get_contact read.

Inputs: zip, cell, city, email, +8 more.

create_opportunityCreate opportunityAInspect

Adds a sales opportunity for a customer with stage, score, budget and expected sale date.

Creates an opportunity in Contractor Foreman as the Opportunities Add drawer does, for a customer from the Directory. It is assigned to the signed-in user. Nobody is emailed. The opportunity number must be unique. Without one it gets OPP- and the UTC date and time (OPP-261021-1213). Returns the saved opportunity.

Inputs: name (required), customer_id (required), zip, city, +8 more.

create_projectCreate projectAInspect

New project for a customer, with number, type, stage, address and dates.

Adds a project in the stage you give (default pending) for a customer from your Directory. Without number the account's next project number is used. Accounts that number projects by hand need one. The project reaches nobody outside your company, so this tool runs without asking. Returns the project as get_project shows it.

Inputs: name (required), customer_id (required), zip, city, +9 more.

create_punchlistCreate punchlistAInspect

New, empty punchlist on a project.

Adds an empty punchlist to the project and returns it as get_punchlist shows it. Items cannot be added through this tool yet, so add them in Contractor Foreman. Nobody is assigned or notified, so this tool runs without asking.

Inputs: name (required), project_id (required).

create_purchase_orderCreate purchase orderAInspect

Creates a draft purchase order to a supplier with line items, optionally for a project.

Creates a Contractor Foreman purchase order in Draft status, ordered by the signed-in user: subject, supplier, project, order date, notes and line items (description, quantity, unit, unit cost, cost type). The supplier is not notified. Sending the PO stays a step in the app. Returns the saved order.

Inputs: items (required), subject (required), vendor_id (required), notes, +2 more.

create_rfiCreate RFIAInspect

Drafts a request for information on a project, with the question and a reply-by date.

Creates a Contractor Foreman RFI in Draft status on a project, from the signed-in user, dated now: title, question, the area and plan sheet it refers to and the date a response is needed by. It is not sent to anyone. Submitting it to the architect or owner stays a step in the app. Returns the saved RFI.

Inputs: title (required), question (required), project_id (required), plan_sheet, +2 more.

create_service_ticketCreate service ticketAInspect

Opens a service ticket for a customer, optionally scheduled for a date and time.

Creates a Contractor Foreman service ticket for a customer from the Directory: title, description, an optional project and the planned service date and time. The service address is the customer's (or the project's). With a date it is Scheduled, without one Unscheduled. Technicians are assigned in the app. The customer is not notified. Returns the saved ticket, with service_time on the 12-hour clock (02:00 PM).

Inputs: title (required), customer_id (required), project_id, description, +2 more.

create_sub_contractCreate sub-contractAInspect

Creates a draft sub-contract with a subcontractor on a project.

Creates a Contractor Foreman sub-contract in Draft status, issued by the signed-in user, for a project and a subcontractor from the Directory, with subject, agreement number and date. This API cannot add scope items, terms or send it for signature. Those stay steps in the app. The subcontractor is not notified. Returns the saved sub-contract.

Inputs: subject (required), project_id (required), contractor_id (required), agreement_number (required), +1 more.

create_todoCreate to-doA
Destructive
Inspect

New to-do, optionally on a project, with due date, priority and assignees.

Adds a to-do and returns it as get_todo shows it. Assignees see it in their Contractor Foreman app.

Inputs: name (required), due_date, due_time, priority, +3 more.

create_work_orderCreate work orderAInspect

Creates an Open work order on a project with subject, description and dates.

Creates a Contractor Foreman work order in Open status on a project, issued by the signed-in user, for the project's customer: subject, description, start and end date. It has no line items. Nobody is notified, and sending it to the customer stays a step in the app. update_work_order_status moves it on. Returns the saved order.

Inputs: subject (required), project_id (required), end_date, start_date, +1 more.

delete_change_orderDelete change orderA
Destructive
Inspect

Deletes a change order or change order request for good.

Deletes the change order and its items. It cannot be undone. To keep the record, use update_change_order with status denied instead.

Inputs: change_order_id (required).

delete_estimateDelete estimateA
Destructive
Inspect

Deletes an estimate for good.

Deletes the estimate and its line items, as Delete in the estimate's menu does. Records made from it (projects, change orders, invoices) stay. It cannot be undone. To keep the history, use update_estimate with status lost instead.

Inputs: estimate_id (required).

delete_invoiceDelete invoiceA
Destructive
Inspect

Deletes an invoice that has no payments, for good.

Deletes the invoice and its items. It cannot be undone. An invoice with payments recorded is refused. For that one, or to keep the record, use update_invoice with status write_off or denied.

Inputs: invoice_id (required).

get_billGet billA
Read-onlyIdempotent
Inspect

One vendor bill with its line items, dates, total, balance due and status.

Reads one Contractor Foreman bill by bill_id: what list_bills gives plus the payment terms and every line item with description, cost type, quantity, unit, unit cost, total and cost code.

Inputs: bill_id (required).

get_change_orderGet change orderA
Read-onlyIdempotent
Inspect

One change order or request with description, status, total and line items.

Everything on one change order or change order request: number, title, status, project, customer, date, the reason (description), the estimate it came from, time delay and the priced line items.

Inputs: change_order_id (required).

get_clock_statusGet clock statusA
Read-onlyIdempotent
Inspect

Who is clocked in right now, whether you are, and this and last week's crew hours.

Reads the Contractor Foreman Time Cards dashboard: the employees clocked in at this moment with their project and clock-in time, whether the signed-in user is clocked in (and that card's id), and the regular, overtime and total hours of the whole team and of the signed-in user for this week and last.

Inputs: no named parameters.

get_contactGet contactA
Read-onlyIdempotent
Inspect

One Directory record in full: contact details, status, services, terms and additional contacts.

Reads one Contractor Foreman Directory record by contact_id: everything list_contacts gives plus a second phone, fax, website, status, services, tags, default payment terms, referral source, the date it was added and the additional contacts kept under it. For leads also stage and quality. Login details, wages and personal ids of employees are left out.

Inputs: contact_id (required).

get_daily_logGet daily logA
Read-onlyIdempotent
Inspect

One daily log: work notes, people and visitors, materials, equipment, weather and delays.

Returns one daily log in full: the work performed, crew notes and employees on site, visitors, materials, equipment used with hours, the weather Contractor Foreman recorded for the date and the address (temperatures in both scales, the day's conditions), your weather notes and any weather or schedule delay. Read only.

Inputs: daily_log_id (required).

get_estimateGet estimateA
Read-onlyIdempotent
Inspect

One estimate with customer, dates, terms, totals and every line item.

Everything on one estimate: status, project, customer contact, estimate and expiry dates, billing type, description, inclusions, exclusions, terms, totals in dollars and the line items by section (type, quantity, unit, unit cost, markup, total, cost code). section_id is what add_estimate_items takes to put new items in a section.

Inputs: estimate_id (required).

get_expenseGet expenseA
Read-onlyIdempotent
Inspect

One expense with amount, date, vendor, project, cost type, cost code and reason.

Reads one Contractor Foreman expense by expense_id: what list_expenses gives plus the cost code and the reason written on it.

Inputs: expense_id (required).

get_inspectionGet inspectionA
Read-onlyIdempotent
Inspect

One inspection with type, project, date, result, agency, inspector and notes.

Reads one Contractor Foreman inspection by inspection_id, with the same fields as list_inspections.

Inputs: inspection_id (required).

get_invoiceGet invoiceA
Read-onlyIdempotent
Inspect

One invoice with customer, dates, terms, line items, payments and balance due.

Everything on one invoice: status, project, customer and their email, invoice and due dates, terms, retainage, total, amount paid and balance due in dollars, the line items and every payment recorded against it (date, amount, method, status).

Inputs: invoice_id (required).

get_job_costingGet job costingA
Read-onlyIdempotent
Inspect

Estimated and actual cost per cost code for one project, with the difference and totals.

Sums the project's Job Cost Actual report per cost code: contract value, estimated cost (from the Schedule of Values or the approved estimates, plus change orders), actual cost split into bills, expenses, time cards and equipment, the difference (estimated minus actual, negative means over) and the amount invoiced. Time card hours are priced at labor_rate (default burden_rate). Costs with no cost code are under Unassigned. Amounts are in dollars. Read only.

Inputs: project_id (required), labor_rate, budget_from.

get_opportunityGet opportunityA
Read-onlyIdempotent
Inspect

One opportunity in full: customer contact, stage, score, budget, notes and last activity.

Reads one Contractor Foreman opportunity by opportunity_id: what list_opportunities gives plus the customer's email and phone, the notes and the subject of the last sales activity.

Inputs: opportunity_id (required).

get_projectGet projectA
Read-onlyIdempotent
Inspect

One project: customer, address, stage, dates, contract amounts, costs, billing and retainage.

Returns one project. The revised contract amount is the original contract plus approved change orders, as the project shows it. Costs are budgeted, committed and actual. Billing is invoiced, paid and outstanding invoices, with retainage held shown apart. Amounts are in dollars. Use project_id from list_projects.

Inputs: project_id (required).

get_punchlistGet punchlistA
Read-onlyIdempotent
Inspect

One punchlist: project, address, customer and how many items are open and completed.

Returns one punchlist with its project, the project address and customer, the number of open and completed items, who made it and when. The items themselves are not returned yet: open the punchlist in Contractor Foreman to see them. Read only.

Inputs: punchlist_id (required).

get_purchase_orderGet purchase orderA
Read-onlyIdempotent
Inspect

One purchase order with supplier, dates, status and its line items.

Reads one Contractor Foreman purchase order by purchase_order_id: what list_purchase_orders gives plus every line item with description, cost type, quantity, unit, unit cost, total and cost code.

Inputs: purchase_order_id (required).

get_rfiGet RFIA
Read-onlyIdempotent
Inspect

One RFI with its question, dates, answer and status.

Reads one Contractor Foreman RFI by rfi_id, with the same fields as list_rfis.

Inputs: rfi_id (required).

get_service_ticketGet service ticketA
Read-onlyIdempotent
Inspect

One service ticket with customer, service address, schedule, technicians and priority.

Reads one Contractor Foreman service ticket by service_ticket_id: what list_service_tickets gives plus the priority, planned duration, service address, the customer's phone and the hours logged on it.

Inputs: service_ticket_id (required).

get_sub_contractGet sub-contractA
Read-onlyIdempotent
Inspect

One sub-contract with subcontractor, amounts, retainage, scope of work and items.

Reads one Contractor Foreman sub-contract by sub_contract_id: what list_sub_contracts gives plus the scope of work text (HTML as saved) and the items added in the app, with quantity, unit cost, total and cost code. paid and balance come back null here. list_sub_contracts has them.

Inputs: sub_contract_id (required).

get_submittalGet submittalA
Read-onlyIdempotent
Inspect

One submittal with plan sheet, specification section, status, dates and its items.

Reads one Contractor Foreman submittal by submittal_id: what list_submittals gives plus the plan sheet and specification section and each submitted item with manufacturer, status and the date it was sent back.

Inputs: submittal_id (required).

get_time_cardGet time cardA
Read-onlyIdempotent
Inspect

One time card or crew sheet with hours per employee and cost code.

Reads one Contractor Foreman time card by timecard_id: what list_time_cards gives plus one entry per employee and cost code with the hours worked and the entry's notes. A crew sheet lists every crew member.

Inputs: timecard_id (required).

get_todoGet to-doB
Read-onlyIdempotent
Inspect

One to-do: description, project, priority, status, due date, assignees and checklist.

Returns one to-do with its description, due date and time, assignees and checklist items. Read only.

Inputs: todo_id (required).

get_work_orderGet work orderA
Read-onlyIdempotent
Inspect

One work order with project, customer, status, dates, location, notes and items.

Reads one Contractor Foreman work order by work_order_id: what list_work_orders gives plus the location, notes and line items with quantity, unit cost and total.

Inputs: work_order_id (required).

list_billsList billsA
Read-onlyIdempotent
Inspect

Vendor bills with vendor, project, dates, total, balance due and status.

Reads the Contractor Foreman Bills list, newest first: bill number, subject, vendor, project, bill date, due date, total, balance still due and status (Open, Paid). Filter by project or search. get_bill adds the line items.

Inputs: limit, cursor, search, project_id.

list_change_ordersList change ordersA
Read-onlyIdempotent
Inspect

Change orders and change order requests, newest first, with status, project and total.

The Change Orders list: number, title, kind (change_order or request), status, project, customer, date and total in dollars. Filter by project, kind, status or a search over title and number. Archived ones only with include_archived. Change orders have the statuses open, pending_approval, on_hold, approved, denied, billed. Requests have draft, on_hold, approved, denied, closed. A status that does not fit the kind stops the call. get_change_order gives the line items.

Inputs: kind, limit, cursor, search, +3 more.

list_contactsList contactsA
Read-onlyIdempotent
Inspect

Customers, employees, contractors, vendors and misc contacts from the Directory.

Reads the Contractor Foreman Directory: active contacts with their type, name, company, title, email, phone, cell and address. Filter by type or search by name, company, email or phone. contact_id is the id other tools ask for as customer_id, vendor_id, contractor_id or employee_id. Leads have their own tool, list_leads.

Inputs: type, limit, cursor, search.

list_cost_codesList cost codesA
Read-onlyIdempotent
Inspect

The company's cost codes, to put on estimate, change order and invoice items.

Every active cost code with its code number, name and parent group. cost_code_id is what the item tools take. search narrows by code or name.

Inputs: search.

list_cost_itemsList cost itemsA
Read-onlyIdempotent
Inspect

Saved cost items with unit, unit cost and markup, to price estimate and change order lines.

The Cost Items Database: name, type, unit, your unit cost in dollars, default markup, cost code, SKU and notes. Use the values as line items in create_estimate, add_estimate_items or create_change_order. Filter by type or a name search. Subcontractor and other items are picked out of each page of all items, so such a page can hold fewer than limit. Keep the cursor going until next_cursor is null.

Inputs: type, limit, cursor, search.

list_daily_logsList daily logsA
Read-onlyIdempotent
Inspect

Daily logs by date, optionally for one project and a date range.

Returns daily logs in the order of the Daily Logs list, with date, arrival time, project and who wrote them, and total, the count of logs that match. Filter by project and by from/to dates (both inclusive). get_daily_log gives one log in full: notes, people, materials, equipment and the weather. Pages hold up to 100 logs; pass next_cursor back as cursor.

Inputs: to, from, limit, cursor, +2 more.

list_estimatesList estimatesA
Read-onlyIdempotent
Inspect

Estimates, newest first, with status, project, customer and total.

The Estimates list: number, title, status, project, customer, dates and total in dollars. Filter by project, status or a search over title, number and customer. Archived estimates only with include_archived. get_estimate gives the line items.

Inputs: limit, cursor, search, status, +2 more.

list_expensesList expensesA
Read-onlyIdempotent
Inspect

Expenses with amount, date, vendor, project, cost type and who paid.

Reads the Contractor Foreman Expenses list, last added first: name, amount with tax, date, vendor, project, cost type (Material, Labor, Equipment ..), who paid it and through what, and whether it is billable to the customer. Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_inspectionsList inspectionsA
Read-onlyIdempotent
Inspect

Inspections with project, type, date, result, agency and permit number.

Reads the Contractor Foreman Inspections list, newest first: number, inspection type, project, date and time, status (Draft, Pass, Fail, Re-Inspect), agency, inspector, permit number, assignee and notes. Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_invoicesList invoicesA
Read-onlyIdempotent
Inspect

Invoices, newest first, with status, totals, balance due and an overdue flag.

The Invoices list: number, status (draft, submitted, on_hold, paid, denied, write_off), project, customer, invoice and due dates, total and balance due in dollars, and overdue (past the due date with a balance). Archived invoices are left out. unpaid_only keeps submitted and on-hold invoices that still have a balance. status, when given, replaces the unpaid_only status filter. unpaid_only and due_before filter the page you get, so a page can hold fewer than limit. Keep the cursor going until next_cursor is null. get_invoice gives the items and payments.

Inputs: limit, cursor, search, status, +4 more.

list_leadsList leadsA
Read-onlyIdempotent
Inspect

Sales leads with contact details, stage and quality score.

Reads the active leads in the Contractor Foreman Directory: name, company, email, phone, address, stage (received, pending, qualifying, qualified, quoted, awarded, lost) and quality from 1 to 5. Search by name, company, email or phone. Opportunities (deals tied to a customer) are list_opportunities.

Inputs: limit, cursor, search.

list_opportunitiesList opportunitiesA
Read-onlyIdempotent
Inspect

Sales opportunities with customer, stage, score, budget and expected sale date.

Reads the Contractor Foreman Opportunities list: deals for a customer before they turn into a project, at every stage, with number, name, stage (received, pending, qualifying, qualified, quoted, awarded, lost), score 1 to 5, budget in the account currency, estimated sales date and who it is assigned to. Search by name, number or customer.

Inputs: limit, cursor, search.

list_paymentsList paymentsA
Read-onlyIdempotent
Inspect

Payments received on invoices, newest first, with amount, method and invoice.

The Payments list: date, amount in dollars, method, status (received, in_review, verified, failed), notes, the invoice it pays, customer and project. get_invoice shows the payments of one invoice.

Inputs: limit, cursor, project_id, customer_id.

list_project_crew_hoursList project crew hoursA
Read-onlyIdempotent
Inspect

Hours and labor cost logged on one project, per employee and per day and cost code.

Reads the time logged on a Contractor Foreman project (the project's Time Cards tab): every entry with the day, employee, cost code, regular and overtime hours and labor cost, plus a sum per employee (most hours first) and the project total. days counts the distinct days an employee logged. Cost uses the wages in the Directory and is 0 when no wage is set. Optional date range.

Inputs: project_id (required), end_date, start_date.

list_project_filesList project filesA
Read-onlyIdempotent
Inspect

Photos and documents on a project, with name, size and a download link.

Reads a Contractor Foreman project's Files tab, newest first: file name, title, whether it is an image, size, notes, tags, when it was added and a download link. The app signs the links and they expire about 30 days after the call (the expires parameter). Call again for fresh ones.

Inputs: project_id (required).

list_project_notesList project notesA
Read-onlyIdempotent
Inspect

The notes on a project's Notes tab, with author and time.

Reads the notes kept on a Contractor Foreman project's Notes tab, oldest first: title, text, who added it, when (in the account's date format) and how many files are attached.

Inputs: project_id (required).

list_projectsList projectsA
Read-onlyIdempotent
Inspect

Projects with customer, stage, dates, contract amount, costs and percent complete.

Returns active (not archived) projects in the order of the Projects list. Completed projects are left out unless include_completed is true or status asks for them. search matches the project name, number or customer. Amounts are in the account's currency: contract amount without tax, budgeted, committed and actual cost, invoiced and paid. Pages hold up to 100 projects; pass next_cursor back as cursor.

Inputs: limit, cursor, search, status, +1 more.

list_punchlistsList punchlistsA
Read-onlyIdempotent
Inspect

Punchlists with project, status, open and completed item counts and who the items are assigned to.

Returns punchlists, optionally for one project, with the number of open and completed items and the people their items are assigned to. status is the one the Punchlists list shows. Pages hold up to 100 punchlists; pass next_cursor back as cursor.

Inputs: limit, cursor, search, project_id.

list_purchase_ordersList purchase ordersA
Read-onlyIdempotent
Inspect

Purchase orders with supplier, project, order date, total and status.

Reads the Contractor Foreman Purchase Orders list, newest first: PO number, subject, supplier, project, order and delivery date, total, status (Draft, Submitted, Approved, Received, Closed ..) and who ordered it. Filter by project or search. get_purchase_order adds the line items.

Inputs: limit, cursor, search, project_id.

list_rfisList RFIsA
Read-onlyIdempotent
Inspect

Requests for information with question, project, dates, answer and status.

Reads the RFIs in Contractor Foreman's RFI & Notices module, newest first: number, title, the question, area and plan sheet it refers to, project, date, response needed by, response received, the answer and status (Draft, Submitted, Outstanding, Received, Closed). Schedule and compliance notices from the same module are left out, so a page can hold fewer than limit. Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_schedule_tasksList schedule tasksA
Read-onlyIdempotent
Inspect

Gantt schedule tasks of a project: dates, duration, dependencies, assignees, percent complete.

Returns the tasks of the project schedule in Gantt order. kind is task, milestone or summary (a group whose dates follow its subtasks). end_date is the task's last day, inclusive. depends_on lists the tasks this one waits for, with the link type and lag in days. Use task_id with update_schedule_task. An empty list means the project has no schedule yet.

Inputs: project_id (required).

list_service_ticketsList service ticketsB
Read-onlyIdempotent
Inspect

Service tickets with customer, status, service date and time and technicians.

Reads the Contractor Foreman Service Tickets list, newest first: ticket number, title, description, status (Unscheduled, Scheduled, En Route, Checked-In, Completed ..), customer, project, service date and time and the assigned technicians. Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_sub_contractsList sub-contractsA
Read-onlyIdempotent
Inspect

Sub-contracts with subcontractor, project, amount, billed, paid, balance and status.

Reads the Contractor Foreman Sub-Contracts list, newest first: agreement number, subject, subcontractor, project, date, contract total, amount billed and paid, balance, retainage percent and status (Draft, Submitted, Committed, Approved ..). Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_submittalsList submittalsA
Read-onlyIdempotent
Inspect

Submittals with project, status, date received, due date and approver.

Reads the Contractor Foreman Submittals list, newest first: number, title, project, status (Draft, Submitted, Pending, Response Received, Approved, Rejected), date received, due date, who it is assigned to and who approved it. Filter by project or search.

Inputs: limit, cursor, search, project_id.

list_time_cardsList time cardsA
Read-onlyIdempotent
Inspect

Time cards with employee or crew, project, clock-in and clock-out times and hours, newest first.

Reads the Contractor Foreman Time Cards list, newest first: employee cards and crew sheets with the project, day, clock-in and clock-out time, hours worked and break hours. A card still running has running true and no hours yet. Filter by a date range, a project or an employee. get_time_card gives one card's entries per person and cost code.

Inputs: limit, cursor, end_date, project_id, +2 more.

list_todosList to-dosA
Read-onlyIdempotent
Inspect

To-dos with project, priority, status, due date and assignees.

Returns to-dos, optionally for one project, one status (open, incomplete, complete) or only those assigned to you. get_todo gives one with its description and checklist. Pages hold up to 100 to-dos; pass next_cursor back as cursor.

Inputs: limit, cursor, search, status, +2 more.

list_work_ordersList work ordersA
Read-onlyIdempotent
Inspect

Work orders with project, customer, status, dates, total and assignee.

Reads the Contractor Foreman Work Orders list, newest first: number, subject, description, project, customer, status (Open, Estimating, Submitted, Approved, Canceled, Completed), start and end date, total and who it is assigned to. Filter by project or search.

Inputs: limit, cursor, search, project_id.

record_inspection_resultRecord inspection resultA
Idempotent
Inspect

Marks an inspection passed, failed or to re-inspect, optionally with notes.

Sets the status of a Contractor Foreman inspection to pass, fail, re_inspect or back to draft, as the status field on its page does, and optionally replaces its notes (corrections the inspector asked for). Nobody is notified. Returns the inspection as saved.

Inputs: result (required), inspection_id (required), notes.

record_paymentRecord paymentAInspect

Records a payment you received against an invoice.

Adds a payment to an invoice, as Add Payment does: amount in dollars, method (bank_transfer, cash, check, credit_card, other), date, status (received, in_review, verified, failed) and notes. It only records money already received. It charges nobody and emails nobody. The invoice must be submitted (update_invoice) and the amount cannot exceed the balance due. A payment that clears the balance marks the invoice paid.

Inputs: amount (required), method (required), invoice_id (required), date, +2 more.

remove_estimate_itemsRemove estimate itemsA
Destructive
Inspect

Deletes line items from an estimate.

Deletes the given line items (item_id from get_estimate) and returns the new estimate total. An item_id that is not on the estimate stops the call before anything is deleted. The app refuses while the estimate is pending_approval, approved or completed: set it back to estimating with update_estimate first.

Inputs: item_ids (required), estimate_id (required).

send_change_orderSend change orderA
Destructive
Inspect

Emails the change order as a PDF to the customer or to the addresses you give.

Sends the change order (or request) PDF by email from Contractor Foreman, as the panel's View/Email PDF does. Without to it goes to the project's customer, and a customer without an email stops the call. The status does not change: update_change_order sets pending_approval or approved.

Inputs: change_order_id (required), to, copy_me, message, +1 more.

send_estimateSend estimateA
Destructive
Inspect

Emails the estimate as a PDF to the customer or to the addresses you give.

Sends the customer version of the estimate PDF by email from Contractor Foreman, as the panel's View/Email PDF does. Without to it goes to the estimate's customer, and a customer without an email stops the call. The estimate's status does not change. update_estimate sets it (pending_approval, approved).

Inputs: estimate_id (required), to, copy_me, message, +1 more.

send_invoiceSend invoiceA
Destructive
Inspect

Emails the invoice as a PDF to the customer or to the addresses you give.

Sends the invoice PDF by email from Contractor Foreman, as the panel's View/Email PDF does. Without to it goes to the invoice's customer, and a customer without an email stops the call. The invoice needs a due date (update_invoice). Sending does not change the status: update_invoice with status submitted marks it sent.

Inputs: invoice_id (required), to, copy_me, message, +1 more.

update_change_orderUpdate change orderAInspect

Changes a change order's status, title, reason or date.

Sets only the fields you pass. Change order statuses: open, pending_approval, on_hold, approved (Unbilled/Approved, counts toward the contract), denied, billed. Change order request statuses: draft, on_hold, approved, denied, closed. A status of the other kind stops the call. Nobody is emailed. send_change_order does that.

Inputs: change_order_id (required), date, title, status, +1 more.

update_daily_logUpdate daily logAInspect

Change the notes, times, people, deliveries, weather notes or delays of a daily log.

Replaces only the fields you pass and returns the log as get_daily_log shows it. Text fields are replaced, not appended: read the log first to add to its notes. materials_delivered replaces the material notes. weather_delay, schedule_delay and visitors can mark a delay or a visit but not clear it. The log date and project do not change. The log reaches no client or crew, so this tool runs without asking.

Inputs: daily_log_id (required), notes, people, visitors, +7 more.

update_estimateUpdate estimateAInspect

Changes an estimate's status, title, dates, description, inclusions or exclusions.

Sets only the fields you pass. status moves the estimate on the Estimates board: estimating, pending_approval, on_hold, re_estimating, approved, completed or lost. Marking it approved here does not email anyone. send_estimate sends it. Line items change with add_estimate_items and remove_estimate_items.

Inputs: estimate_id (required), title, status, exclusions, +4 more.

update_invoiceUpdate invoiceAInspect

Changes an invoice's status, invoice date, due date or description.

Sets only the fields you pass. Statuses: draft, submitted (sent to the customer, payments can be recorded), on_hold, paid, denied, write_off. Contractor Foreman needs a due date on every change, so an invoice without one needs due_date in the same call. Nobody is emailed. send_invoice does that.

Inputs: invoice_id (required), status, due_date, description, +1 more.

update_projectUpdate projectAInspect

Change a project's name, stage, type, address, dates or description.

Changes only the fields you pass and returns the project as get_project shows it. A completed project drops out of list_projects unless include_completed is true. Editing the schedule can move the project dates again. Nothing reaches the customer, so this tool runs without asking.

Inputs: project_id (required), zip, city, name, +8 more.

update_schedule_taskUpdate schedule taskAInspect

Change the name, dates, length or percent complete of a task on the project schedule.

Changes one task and returns it as the schedule shows it afterwards. start_date alone moves the task and keeps its length; end_date or duration_days change the length. Tasks that depend on it are not moved: check depends_on in list_schedule_tasks and move them too. The project's start and end dates follow the schedule. A schedule edit reaches nobody outside your company and one more call undoes it, so this tool runs without asking.

Inputs: task_id (required), project_id (required), name, end_date, +3 more.

update_service_ticket_statusUpdate service ticket statusA
Idempotent
Inspect

Moves a service ticket to scheduled, en route, checked in, completed, closed and so on.

Sets the status of a Contractor Foreman service ticket as the status field on its page does: unscheduled, scheduled, en_route, checked_in, requires_followup, canceled, completed or closed. The app's own en-route and completion emails to the customer are separate buttons and are not sent. Completed moves the service date to today, as the app does. Returns the ticket as saved.

Inputs: status (required), service_ticket_id (required).

update_todoUpdate to-doAInspect

Change a to-do's name, description, due date, priority or status, e.g. mark it complete.

Changes only the fields you pass and returns the to-do as get_todo shows it. status complete closes it, open reopens it. Assignees and checklist items are not changed. Nothing is sent to anyone, so this tool runs without asking.

Inputs: todo_id (required), name, status, due_date, +3 more.

update_work_order_statusUpdate work order statusA
Idempotent
Inspect

Moves a work order to open, estimating, submitted, approved, canceled or completed.

Sets the status of a Contractor Foreman work order as the status field on its page does. The status in the answer is the label the company uses for it. Nobody is emailed. Returns the work order as saved.

Inputs: status (required), work_order_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 89 tools

    Disambiguation4/5

    The tools are mostly organized around distinct resources and actions, so an agent can usually tell a project tool from an estimate, invoice, or change order tool. Some boundaries blur around time tracking (get_clock_status, list_time_cards, get_time_card, list_project_crew_hours) and contacts versus leads, though the descriptions provide enough context.

    Naming Consistency5/5

    Every tool name uses snake_case with a verb_noun structure. Verbs such as get, list, create, update, delete, add, remove, send, and record are used predictably by operation type.

    Tool Count1/5

    With 89 tools, the server is far beyond a typical well-scoped MCP surface and risks overwhelming tool selection. Even for a broad construction ERP domain, this level of granularity is too large for a single cohesive tool set.

    Completeness3/5

    Core financial workflows such as estimates, invoices, change orders, and payments have strong lifecycle coverage. However, many modules have notable dead ends: punchlists cannot add items, files cannot be uploaded, and submittals, RFIs, contacts, leads, opportunities, bills, purchase orders, and sub-contracts lack key update, delete, or send operations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Contractor+ MCP server for ChatGPT, Claude and any AI agent: create estimate, send estimate, create job, send invoice and list unpaid invoices in your own Contractor+ account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Contractor+ yourself; Cotlet does not store your password and you need no Contractor+ API key. About the official Contractor+ API: Contractor+ has a public API with an account API key, but it comes with the Pro Team plan, together with Zapier; Freedom and Pro do not include it (checked 8 Nov 2026). There is no official MCP server. Setup and FAQ: https://cotlet.dev/integrations/contractor-plus-api-mcp-server

    • Procore MCP server for ChatGPT, Claude and any AI agent: list RFIs, create RFI, list submittals, create punch list item, create observation and add manpower entry in your own Procore account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Procore yourself; Cotlet does not store your password and you need no Procore API key. About the official Procore API: Procore has a REST API with OAuth 2.0 and a sandbox, but publishes no MCP server for your own AI agent (checked 5 Nov 2026). The API runs through an app that you register in the Developer Portal and a company admin installs. Setup and FAQ: https://cotlet.dev/integrations/procore-api-mcp-server

      https://cotlet.dev/mcp/v1/procore
    • Buildertrend MCP server for ChatGPT, Claude and any AI agent: get schedule, create daily log, create change order and list selections in your own Buildertrend account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Buildertrend yourself; Cotlet does not store your password and you need no Buildertrend API key. About the official Buildertrend API: Buildertrend publishes no API docs or self-serve keys for customers; it connects through its Marketplace integrations (checked 11 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/buildertrend-api-mcp-server

    • Joist MCP server for ChatGPT, Claude and any AI agent: create estimate, convert estimate to invoice, list invoices, add client and record payment in your own Joist account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Joist yourself; Cotlet does not store your password and you need no Joist API key. About the official Joist API: Joist has no public API (checked 26 Oct 2026): its help center and pricing page document none, and there are no webhooks. The only built-in link out is QuickBooks Sync, part of Joist Pro, which copies issued estimates and invoices to QuickBooks Online once a night. Setup and FAQ: https://cotlet.dev/integrations/joist-api-mcp-server

      https://cotlet.dev/mcp/v1/joist

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding tools to drive the user's real, already-logged-in Chrome through an MCP stdio interface, exposing 25 tools for navigating, clicking, typing, reading pages, taking screenshots, capturing network traffic, and accessing cookies and storage. The bundled Chrome extension talks to a local bridge instead of an open remote-debugging port, so logged-in sessions and bot-detection-proof human browsing work without extra setup.
      1 npm
      ISC
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to read and change jobs, job status, customers, quotes with line items, invoices, quote and invoice email, payments, and Scheduler bookings in an account by reusing the user's own signed-in Chrome session, with no official API keys needed. Ships read-only hints and confirmation prompts for tools that reach other people, and can be run over stdio or streamable HTTP.
      2
      22
      403 PyPI
      6
      Elastic 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server paired with a Chrome extension that lets any MCP-compatible AI agent drive the browser you're already signed into — navigating, clicking, filling forms, scraping and extracting structured records using your real profile, cookies and logged-in sessions. It exposes 28 browser_* tools over stdio and relays them to the extension on localhost, with capabilities like paginated record extraction, ref-tagged snapshots, screenshots, and opt-in file uploads.
      254 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP-capable AI agent to operate the user's own everyday Chrome browser with all existing login sessions intact, offering 22 tools for reading page/network data, filling forms, clicking, batch multi-step actions, and handing CAPTCHAs or confirmations back to the human — without API keys, debug ports, or launch flags.
      MIT