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
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":{}}}'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.