`shovels_contractors_search`

Pack: shovels · Endpoint: https://gateway.pipeworx.io/shovels/mcp

Search US construction contractors scoped to a location, with license, work history and aggregate job value. Requires a geo_id (state code, ZIP, or Shovels geo_id from shovels_address_search) plus a permit date range (permit_from / permit_to, YYYY-MM-DD). Job-value fields are returned in both cents and dollars. Example: shovels_contractors_search({ geo_id: “94103”, permit_from: “2023-01-01”, permit_to: “2024-12-31”, contractor_name: “solar”, _apiKey: “your-key” })

Parameters

Name	Type	Required	Description
`geo_id`	string	yes	Location scope: a US state code (“CA”), a ZIP code (“94103”), or a Shovels geo_id from shovels_address_search.
`permit_from`	string	yes	Consider permits that started on or after this date (YYYY-MM-DD).
`permit_to`	string	yes	Consider permits that started on or before this date (YYYY-MM-DD).
`contractor_name`	string	no	Filter by contractor name (partial match, min 3 chars).
`contractor_license`	string	no	Filter by contractor license number.
`contractor_classification_derived`	array	no	Filter by derived contractor classification/specialty. Prefix with ”-” to exclude.
`items`	string	no
`permit_tags`	array	no	Filter by work-type tags of the contractor’s permits. Prefix ”-” to exclude.
`items`	string	no
`property_type`	string	no	Filter by property type: residential, commercial, industrial, etc.
`contractor_min_total_job_value`	number	no	Minimum total job value across the contractor’s permits, in CENTS.
`contractor_min_total_permits_count`	number	no	Minimum number of permits the contractor has.
`size`	number	no	Results per page (1-100, default 50).
`cursor`	string	no	Pagination cursor from a previous response `next_cursor`.
`include_count`	boolean	no	Include an approximate total_count on the first page (default false).
`_apiKey`	string	yes	Shovels API key (X-API-Key). Sign up at ${SIGNUP_URL}

Example call

Arguments

{
  "geo_id": "CA",
  "permit_from": "2023-01-01",
  "permit_to": "2024-12-31",
  "_apiKey": "your-shovels-api-key"
}

curl

curl -X POST https://gateway.pipeworx.io/shovels/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"shovels_contractors_search","arguments":{"geo_id":"CA","permit_from":"2023-01-01","permit_to":"2024-12-31","_apiKey":"your-shovels-api-key"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('shovels_contractors_search', {
  "geo_id": "CA",
  "permit_from": "2023-01-01",
  "permit_to": "2024-12-31",
  "_apiKey": "your-shovels-api-key"
});

More examples

{
  "geo_id": "94103",
  "permit_from": "2023-01-01",
  "permit_to": "2024-12-31",
  "contractor_name": "solar",
  "contractor_min_total_job_value": 500000,
  "_apiKey": "your-shovels-api-key"
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "shovels": {
      "url": "https://gateway.pipeworx.io/shovels/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

shovels_contractors_search