@3bids/mcp-contractor

MCP server for 3Bids contractors - manage your home services business from Claude Code.

Overview

This MCP (Model Context Protocol) server powers Company Brain: a Claude Code workspace for contractors to inspect, operate, and improve the business through 3Bids.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│  3bids MCP Server │────▶│  Convex Backend │
│   (contractor)  │◀────│  (this package)   │◀────│ original-peacock│
└─────────────────┘     └──────────────────┘     └─────────────────┘

Installation

For a pitch-deck demo, use the short path:

npx --yes @3bids/mcp-contractor demo

That command stores demo MCP credentials and prints the Claude Code MCP setup command. Add --claude to run the Claude Code setup automatically.

npm install -g @3bids/mcp-contractor

Or configure directly in Claude Code:

claude mcp add 3bids -s user -- npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp serve --bundle headless

Headless Bundle

This package defaults to a restricted headless bundle that exposes high-signal read and preview tools. The managed OpenClaw bundle is available through the explicit --bundle openclaw flag, and the full catalog requires both --bundle full and THREEBIDS_ENABLE_FULL_MCP=1 in a trusted local operator environment.

For the managed Company Brain setup, generate an MCP token in the contractor app and download Company Brain for Claude Code from Settings -> API Tokens. The zip contains Claude skills, playbooks, and local context files for headless operation.

Canonical allowlist:

• Source of truth: src/tools/openclaw.ts
• Entry point: serve or serve --bundle headless
• OpenClaw bundle: serve --bundle openclaw
• Dedicated binary: 3bids-mcp-openclaw
• Build target: npm run build:openclaw
• NPM script: npm run start:openclaw

Example:

npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login
npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp serve

The default headless bundle intentionally excludes onboarding setup tools, internal admin tools, SMS/campaign launchers, payout actions, and other financial or external side-effect tools.

By default, the package connects to the production Convex site: https://original-peacock-353.convex.site.

Set CONVEX_SITE_URL only when you intentionally need a non-production deployment, and pair non-production origins with THREEBIDS_MCP_ALLOW_UNTRUSTED_ORIGIN=1.

Getting Your MCP Token

1. Log in to the 3Bids contractor app
2. Go to Contractor -> Settings -> API Tokens
3. Click Generate New Token
4. Run npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login If the browser flow is unavailable, run npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login --manual and paste the token into the stdin prompt.

Available Tools (full bundle examples)

Jobs (Read-Only)

| Tool | Description | |------|-------------| | search_jobs | Search available jobs by keyword, category, location, budget | | get_job | Get full job details including your bid status | | get_job_stats | Get your job statistics | | get_nearby_jobs | Find jobs near your location | | get_recommended_jobs | Get AI-recommended jobs |

Bids (Read/Write)

| Tool | Description | |------|-------------| | list_bids | List your bids with status filter | | get_bid | Get bid details | | submit_bid | Submit a new bid | | update_bid | Update a pending bid | | withdraw_bid | Withdraw a bid | | get_bid_stats | Get bid statistics |

Messages (Read/Write)

| Tool | Description | |------|-------------| | list_conversations | List job conversations | | get_messages | Get messages for a job | | send_message | Send a message | | get_unread_count | Get unread message count | | list_quick_replies | Get message templates |

Earnings (Read-Only)

| Tool | Description | |------|-------------| | get_earnings_summary | Get financial summary | | get_payment_history | Get payout history | | get_pending_payouts | Get pending releases | | get_escrow_detail | Get project breakdown | | get_tax_summary | Get tax-year summary |

Dispatch (Read/Write)

| Tool | Description | |------|-------------| | get_dispatch_board | Get today's dispatch overview | | list_assignments | List job assignments | | get_assignment | Get assignment details | | create_assignment | Schedule a job | | update_assignment_status | Update assignment status | | get_today_route | Get optimized route | | get_team_locations | Get team GPS locations |

Profile (Read/Write)

| Tool | Description | |------|-------------| | get_profile | Get your profile | | update_profile | Update profile info | | get_verification_status | Get verification status | | get_profile_completion | Get profile completion % |

Portfolio (Read/Write)

| Tool | Description | |------|-------------| | list_portfolio | List portfolio items | | add_portfolio_item | Add portfolio item | | update_portfolio_item | Update portfolio item | | remove_portfolio_item | Remove portfolio item |

Active Jobs (Read/Write)

| Tool | Description | |------|-------------| | get_active_jobs | Get non-completed jobs | | mark_job_started | Start work on a job | | update_job_progress | Update job progress | | request_job_completion | Request completion review |

Example Usage

In Claude Code:

> Show me open plumbing jobs near me

Found 12 plumbing jobs within 25 miles:
1. Water heater replacement - $800-1200 - 3.2 miles
2. Bathroom remodel plumbing - $2000-3500 - 5.8 miles
...

> Submit a $950 bid on job #1 with note "Licensed plumber, can start tomorrow"

Bid submitted successfully!
- Job: Water heater replacement (#JOB-2024-1234)
- Amount: $950
- Status: Pending

> What's my earnings this month?

Earnings Summary:
- This month: $4,850
- Pending payouts: $1,200
- In project: $3,400
- Last month: $6,200

> Show today's dispatch board

Today's Schedule (Feb 12, 2026):
- 9:00 AM - Kitchen sink repair @ 123 Main St (en route)
- 11:30 AM - Water heater install @ 456 Oak Ave (scheduled)
- 2:00 PM - Bathroom fixture @ 789 Pine St (scheduled)

Total: 3 jobs | 1 en route | 2 scheduled

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli/index.js login
node dist/cli/index.js serve

# Watch mode
npm run dev

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CONVEX_SITE_URL | No | Explicit Convex site URL override. Defaults to production and rejects untrusted origins without local-development opt-in. | | THREEBIDS_MCP_CONVEX_URL | No | Alternate explicit Convex site URL override for local development. | | THREEBIDS_MCP_ALLOW_UNTRUSTED_ORIGIN | No | Set to 1 only for local development against non-production Convex origins. | | THREEBIDS_ENABLE_FULL_MCP | No | Set to 1 only for trusted operators who need serve --bundle full. | | THREEBIDS_API_TOKEN | No | Internal/legacy token override only. User-facing token argv flows such as login --token are blocked; use npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login. |

Security

• Tokens are validated on every request via Clerk JWKS
• Only contractor accounts can authenticate
• Self-serve tokens default to read-only access and expire after 30 days
• Rate limiting enforced per-contractor

Support

• Issues: https://github.com/mindcraftreader/3bidrn/issues
• Docs: https://docs.3bids.io/mcp
• Email: [email protected]

License

MIT