# Shovels MCP > Shovels MCP Server is a construction and permit data platform that lets your AI client audit real estate records. It gives you instant access to licensed contractors, active building permits, and market intelligence across specific geographic areas. You can ask your agent to find all roofing professionals near an address or pull aggregated statistics on remodeling permits for a whole county—all without touching a dashboard. ## Overview - **Category:** real-estate - **Price:** Free - **Tags:** building-permits, contractor-data, market-intelligence, auditing, public-records ## Description **Shovels gives your AI client direct access to massive construction and permit records.** You don't gotta click through some bloated dashboard; you just talk to your agent, and it pulls the data you need. Your agent handles all the heavy lifting across three main areas: contractors, permits, and market intelligence. To find licensed pros, you can use `search_contractors` to list professionals based on work type—whether they're doing solar or roofing—property kind, or a ZIP code. If you know exactly who you need, your agent runs `get_contractor_by_license`, confirming their full profile using just their state business license ID. For general contractor details, it pulls specific data for one licensed individual using `get_contractor`. To track activity on the ground, use `get_contractor_activity` to pinpoint any construction crews working near a given address. When you need to look into permits, your agent starts by running `search_permits`, letting you filter records based on an address or a specific permit status. For deep dives, calling `get_permit` gives you the full history and current status of any single building permit record, including its estimated value. To check market viability across a whole area, use `get_permit_stats`; this pulls aggregated statistics so you can analyze overall trends in building activity throughout an entire county or city. Your agent runs these numbers whether you're verifying credentials or checking market movement. It gives you structured data every time. ## Tools ### get_contractor_activity Finds and lists contractors currently working near a specified address. ### get_contractor_by_license Retrieves full contractor profiles using their state business license ID. ### get_contractor Retrieves specific details for a single licensed contractor. ### get_permit_stats Pulls aggregated data to show overall trends in building permit filings by area. ### get_permit Gets the detailed status and history for a specific building permit record. ### search_contractors Searches and lists licensed contractors based on criteria like work type or location. ### search_permits Searches for building permits using key details like address or permit status. ## Prompt Examples **Prompt:** ``` Search for roofing contractors in ZIP 94105. ``` **Response:** ``` I've searched Shovels for roofing professionals in San Francisco (94105). I found 8 active contractors, including 'Bay Area Roofing' and 'Elite Home Exteriors'. Would you like to see their full credentials? ``` **Prompt:** ``` Show me permit stats for Austin, TX. ``` **Response:** ``` Retrieving permit activity for Austin... I see a 15% increase in residential remodeling permits this quarter, with a total of 1,200 active filings. I can break this down by permit type if needed. ``` **Prompt:** ``` Find contractors active near 1600 Amphitheatre Pkwy, Mountain View. ``` **Response:** ``` Scanning work activity near Googleplex... I've identified 12 contractors doing work within a 5-mile radius, mostly focusing on commercial HVAC and electrical upgrades. Shall I list the companies for you? ``` ## Capabilities ### Audit Permits Retrieve full details on any specific building permit using `get_permit`, including its current status and estimated value. ### Find Contractors by Location `search_contractors` lets you list licensed professionals based on work type, property kind, or ZIP code. ### Track Site Activity Pinpoint active construction crews near a given address using `get_contractor_activity`. ### Analyze Market Trends `get_permit_stats` pulls aggregated statistics, letting you analyze building activity across entire counties or cities. ### Verify Licenses Confirm a contractor's status and details immediately using their state business license ID via `get_contractor_by_license`. ## Use Cases ### Pre-Purchase Due Diligence A developer is buying land. He asks his agent: 'What was the last permit filed here, and who worked on it?' The agent runs `search_permits` to find recent records, then calls `get_contractor_activity` using the address to list active crews, giving him a clear picture of development history. ### Compliance Check A property manager needs to audit a contractor. He uses `get_contractor_by_license` first to validate their state ID. Then he runs `search_contractors` for that license type and checks the resulting profile for any compliance gaps. ### Market Opportunity Analysis A market researcher wants to find high-growth areas. They prompt: 'Show me permit stats for all residential remodels in this county.' The agent executes `get_permit_stats`, delivering a quantitative analysis that identifies the best investment zones. ### On-Site Oversight A site supervisor walks past an address and asks: 'Who's operating here right now?' The agent uses `get_contractor_activity` to scan the area, listing 12 active crews specializing in HVAC upgrades. He knows exactly who to talk to. ## Benefits - **Know who is working where.** Instead of driving around looking for signs, use `get_contractor_activity` to instantly list every contractor operating within a 5-mile radius of an address. - **Stop digging through records.** Get the full history and current status of any building permit by calling `get_permit`. You don't need to navigate multiple municipal websites. - **Analyze whole markets at once.** Use `get_permit_stats` to pull aggregated data, letting you compare construction trends between Austin and Dallas with a single prompt. - **Verify contractors in seconds.** Never take a chance on an unlicensed crew. Run the contractor's state ID through `get_contractor_by_license` for instant validation. - **Find exactly what you need.** Use `search_contractors` to filter by specific work types, like 'solar' or 'roofing,' rather than getting a massive list of irrelevant general contractors. ## How It Works The bottom line is you talk to your agent, and it runs all the complex database queries for you. 1. Subscribe to the Shovels server on Vinkius. 2. Enter your unique Shovels.ai API Key into your preferred AI client (Claude, Cursor, etc.). 3. Ask your agent a question like: 'What permits are active near 123 Main St?' and let it run the necessary tools. ## Frequently Asked Questions **How do I use the get_contractor_activity tool with Shovels?** You send your agent a request specifying the address. The `get_contractor_activity` tool then scans that location and lists all licensed contractors currently working within a defined radius. **Is get_permit_stats better than searching for permits?** Yes, they serve different goals. Use `search_permits` when you know the address or general type of permit you need to find. Use `get_permit_stats` when you want to see trends—like how many total residential filings happened this quarter. **Can I check a contractor's license without knowing their name? (Using get_contractor_by_license)** Absolutely. `get_contractor_by_license` is designed to take the state business ID directly, which lets you pull up a profile even if the company has changed names. **Which tool should I use to find roofing contractors in my area? (Using search_contractors)** You start with `search_contractors`. You simply tell your agent you need 'roofing' professionals and the location, and it returns a list of licensed options. **What is required to successfully run the `get_permit` tool?** You must provide a valid Shovels API Key. This key authenticates your connection, giving your agent access to the full permit database. Always treat this key as sensitive credentials. **If I use `search_contractors` and no matching records are found, what does the tool return?** The tool returns a predictable status code along with an empty list object. Your agent can check for this explicit zero-result state instead of failing, allowing you to handle 'no data' gracefully. **Are there rate limits when calling `get_permit_stats`?** Yes, we enforce standard API rate limits. If your agent exceeds the allowed calls per minute, it will return a 429 error. You should implement an exponential backoff retry logic in your code. **Does `get_contractor` provide every piece of contractor data available?** The `get_contractor` tool provides core public records, including license status and contact history. It does not access private financial data or internal company documents. **How do I find solar contractors in a specific ZIP code?** Use the `search_contractors` tool and provide the ZIP code in the `geo_id` parameter and 'solar' in the `work_type` parameter. Your agent will return a list of matching professionals. **Can I see permit activity for a whole city?** Yes! Use the `get_permit_stats` tool with the city name or City/State combination in the `geo_id` parameter to retrieve aggregated construction data for that area. **How do I verify if a contractor has a valid license?** You can use the `get_contractor_by_license` tool with their state business license ID. The returned profile will include their current licensing status and specialty data.