CRM Cleanup with MCP: A Step-by-Step Playbook for HubSpot

CRM cleanup is the job nobody wants: finding contacts with no owner, deals stuck in old stages and companies with half-empty records. It usually falls to a sales ops lead or an admin with a spreadsheet export. MCP changes the first half of that job. An AI assistant can query your HubSpot data in plain English, list what is broken and propose fixes for you to approve.

This playbook uses HubSpot's official MCP server, because HubSpot publishes its tool list and limits. The same pattern works with other CRMs that have an MCP server, but the tool names below are HubSpot's.

What you need

• The HubSpot MCP server. HubSpot's MCP overview says the remote server gives an AI tool "secure read and write access to your HubSpot CRM data." HubSpot hosts it at https://mcp.hubspot.com with OAuth and PKCE. Our HubSpot MCP server profile covers the full tool list and setup.
• An AI client. Claude users can add HubSpot's directory connector without creating a connector in HubSpot; see connect Claude to HubSpot. ChatGPT users can follow connect ChatGPT to HubSpot.
• A HubSpot user with the right permissions. HubSpot says all actions respect the signed-in user's permissions. For the Claude connector, users other than Super Admins need a Super Admin to approve it first, according to HubSpot's Claude connector article.
• A paid Claude plan if you use Claude. HubSpot lists Pro, Max, Team or Enterprise.
• A written cleanup rulebook. Decide in advance what "clean" means: required fields, valid lifecycle stages, which stale deals to close. The AI applies rules; it should not invent them.

The workflow

1. Map your schema. Ask the assistant to call discover_hubspot_schema and search_properties. You get a list of objects and the property names your portal actually uses. HubSpot's integration guide says to confirm property names with search_properties before running query_crm_data.
2. Audit with read tools only. Use search_crm_objects to find records that break your rules, such as contacts with no owner or deals with a close date in the past and an open stage. HubSpot allows up to 5 filter groups with 6 filters each and returns up to 200 results per page.
3. Get counts and summaries. Use query_crm_data for totals, such as open deals by stage. HubSpot notes it does not support joins, subqueries or association traversal, so keep each question simple. Call tool_guidance first, as HubSpot recommends.
4. Check owners. Use search_owners (up to 100 results) to match unowned records to current reps, and to spot records owned by people who have left.
5. Flag likely duplicates. Ask the assistant to compare search results on email domain, company name or phone. HubSpot documents no merge tool, so the output is a review list for a person, not an action.
6. Propose fixes in small batches. Ask for a table of proposed changes: record, field, old value, new value, reason. HubSpot says manage_crm_objects shows a proposed-changes summary and needs explicit confirmation before any create or update.
7. Apply approved updates. Approve batches of 10 or fewer. HubSpot's Claude article says you "can only create or update 10 records at a time." HubSpot also says the server respects conditional field logic and custom pipeline stage validations.
8. Group records for follow-up. Use manage_segment to add records to a static segment, such as "Needs owner review." HubSpot requires confirmation before each segment write.
9. Merge and delete by hand. Work through the duplicate list in HubSpot itself. HubSpot says the Claude connector "does not support delete operations."
10. Fix the source. If the same gaps keep appearing, look at the property definitions. manage_custom_properties and manage_custom_pipelines can change them, but treat those as admin changes, not cleanup.

Example prompts

• "Use discover_hubspot_schema and search_properties to list every contact property we use for lifecycle stage and lead status. Do not change anything."
• "Search CRM objects for open deals with a close date before 1 September 2026. Return deal name, owner, stage and amount as a table."
• "Using query_crm_data, count contacts with no owner, grouped by lifecycle stage."
• "List companies that share the same domain. Show both record IDs so I can merge them in HubSpot. Do not update anything."
• "For these 8 contacts, propose setting the owner to the rep named in the table. Show me the changes before calling manage_crm_objects."

Guardrails

• Read first, for at least one full pass. Run the audit prompts, check the results against HubSpot's own views, and only then turn on writes. Our guide to MCP permissions and approvals explains the client settings.
• Keep approval on for writes. HubSpot recommends setting write tools to Needs Approval in Claude. If you pick Always allow, HubSpot says "edits may occur without asking for approval." That is the setting to avoid during cleanup.
• Use the right person's login. The server acts as the signed-in user. Run cleanup from an account that can see the records but is not a Super Admin unless you need that level.
• Watch for injected text. Notes, emails and form fills are written by outsiders. Read MCP prompt injection before you let an agent act on activity data.
• Know the Sensitive Data rule. HubSpot says that when Sensitive Data is on, the MCP server blocks activity data (calls, emails, meetings, notes, tasks) and conversations. Your audit will not see those objects.
• Keep humans on merges, deletes and schema. These are hard to undo. Leave them in HubSpot, done by a named owner.

For a wider checklist, see the MCP Security Center.

What to measure

Track outcomes you can check in HubSpot, not AI activity:

• Records failing each rule at the start, and after each cleanup round.
• How many proposed changes you approved, edited or rejected. A high rejection rate means your rulebook or prompts need work.
• Duplicates found versus duplicates merged by a person.
• How many of the same problems return within a month. That points to a form, import or integration that needs fixing upstream.
• Time spent by the ops owner per round, logged by that person.

Next step

Run one read-only audit this week and compare it with a manual export. If the findings match, add small approved batches. More task guides live in the MCP playbooks hub. If you want help writing the rulebook and approval setup for your team, book an MCP readiness audit.

Frequently asked questions