Contractor Foreman by Cotlet MCP server

Contractor Foreman API and MCP server, self-hosted

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

It is for technical people who want to run it themselves, for noncommercial use only (license). If you want it running 24/7 on a server, kept working when Contractor Foreman changes its app, for a team or a business, use the hosted version at cotlet.dev.

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

Contents

• How it works
• Requirements
• Install
• Connect your Chrome
• MCP server
• REST API
• Python and the example scripts
• All 89 tools
• Configuration
• Security and your Contractor Foreman account
• Errors
• Self-hosted or hosted

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

Shortened. The full README is on GitHub.