Unofficial MCP + HTTP gateway for Buildertrend. Humans and agents do the work outside Buildertrend. Buildertrend stays the system of record (the copy the office still sees).
This repository also contains the older bill-review web app. New callers
(your app, Grok, Cursor) must use the gateway verbs, not scrape
buildertrend.net themselves.
Unofficial. Not affiliated with, endorsed by, or supported by Buildertrend. Cookie-session access to undocumented internal APIs. Use only against your own account. Review Buildertrend’s terms before deploying.
If you are not technical, you do not need to clone this repo or open a terminal. Open Grok Bot, paste the prompt below, and let the agent install the gateway on its computer — or update it if it is already there. There is no catalog connector named Buildertrend — the agent adds a local connector after you tap Yes.
Set up the Buildertrend Gateway from this GitHub repo. I'm not technical. Follow AGENTS.md and docs/GROK_BOT_SETUP.md. Walk me through it. Don't enable send.
If the gateway is already installed, update it from GitHub now. Do not leave the old checkout. Use the existing copy on Grok Bot's computer. Fetch origin/main. Do not clone a second copy. Keep my .env files and my Buildertrend session. Do not overwrite secrets, cookies, or the dedicated Chrome profile. Run pnpm install or update Python deps only if the lockfile or sidecar deps changed. Restart the local connector after the pull so new verbs load.
Do not set a cron, a routine, or a scheduled git pull. No Friday auto-update. Do not pull unattended. Do not merge pull requests. Do not rebase. Do not enable send.
https://github.com/BuildCal/buildertrend-gateway
The old address https://github.com/BuildCal/buildertrend-extension still redirects here.
When Grok Bot asks to add the Buildertrend Gateway connector, tap Yes. When it shows a Buildertrend sign-in screen, sign in there with a login you are allowed to use — do not paste your password into the chat. Writes stay drafts. Send and pay stay off.
Full walkthrough for humans: docs/GROK_BOT_SETUP.md. Playbook for the agent (read this first if you were only handed the GitHub URL): AGENTS.md.
| Layer | Role |
|---|---|
| Adapter | Cookie-session HTTP to buildertrend.net. Ugly, once. Python bt-service impersonates Chrome TLS. |
| Verbs | Stable names: jobs.list, invoices.get, variations.saveDraft, … |
| MCP + HTTP | One implementation. Agents get MCP tools (bt_jobs_list, …). Apps POST /v1/.... |
Default every write to Draft / Not sent. BT_GATEWAY_ENABLE_SEND=false.
Uncaptured writes return not_captured plus the UI click needed — we do not guess URLs.
apps/
gateway/ TypeScript verbs, MCP, HTTP /v1, GST dummy-line, capture harness
bt-service/ Python FastAPI + curl-cffi (TLS fingerprint). Session store + generic /internal/bt-request
web/ Next.js bill review queue (calls the sidecar; should move onto gateway verbs)
pnpm install
cp apps/gateway/.env.example apps/gateway/.env
# Set BT_SERVICE_URL + BT_SERVICE_INTERNAL_TOKEN after bt-service is up
# Leave BT_GATEWAY_ENABLE_SEND=false
pnpm --filter gateway test
pnpm --filter gateway mcp # stdio MCP
pnpm --filter gateway serve # HTTP :8787Attach a dedicated gateway Chrome profile (not a human daily profile). See apps/gateway/README.md.
Builder id comes from session.status / GlobalInfo after login. Do not
hard-code a tenant id.
Invoice extraction, PO matching, and a human review queue still live in
apps/web. Setup: docs/getting-started.md.
| Doc | What’s in it |
|---|---|
| Use with Grok Bot | Human setup — paste the URL, tap Yes, sign in |
| AGENTS.md | Agent playbook when someone pastes this repo URL |
| Gateway README | Profile, MCP, HTTP, dry_run, send lock |
| Slice C captures | Remaining writes + exact UI clicks |
| API map | Captured routes (no cookies) |
| Architecture | Why the split, review queue, audit log |
| Buildertrend API notes | Sidecar-era bill endpoints |
| Session refresh | Daily cookie-upload ritual |
| Security | Threat model |
- No owner email, no
notify-owners, no invoice Send - No payments, no Xero pay, no “mark ready for payment” unless flagged
- No new real contact/lead/job without
dry_run=falseand sandbox - Do not store credentials in git, MCP logs, or issue comments
- Change-order GST is a dummy line (1/11 of owner price), resolved via Search (
4000 GST). Do not use the native CO tax engine - Project expenses only through bills/POs. Never workers comp / tax / payroll through BT