# HubSpot MCP > HubSpot MCP gives your AI client access to a complete CRM, letting you manage contacts, companies, and deals using natural conversation. Instead of clicking through dashboards, you can ask your agent to find specific accounts, update deal stages, or create new leads—all without ever leaving your workflow. It's like having the entire HubSpot database available as a chat tool. ## Overview - **Category:** industry-titans - **Price:** Free - **Tags:** contact-management, deal-pipelines, lead-nurturing, crm-integration, company-records, sales-operations ## Description Need to manage customer records but hate switching tabs? This MCP connects your AI client directly into your core CRM data, letting you handle sales and marketing operations entirely through conversation. You can ask your agent to pull up company details, search for contacts using complex filters, or even create a brand new lead record. It doesn't just read data; it executes actions—you can link records together (like connecting a contact to a specific deal) or update the stage of an entire pipeline. This level of direct action is what makes Vinkius the essential platform for connecting your AI agents to enterprise systems. You use this MCP when you need conversational access to complex, structured data that normally requires multiple clicks and exports. ## Tools ### link_crm_objects Creates a formal association between two records, such as connecting a Contact to their Company. ### create_contact Adds a brand new contact record to the system. ### remove_contact Permanently deletes an existing contact record from the system. ### get_company_info Retrieves full details about a specific company account. ### get_contact_details Fetches all information related to an individual contact. ### get_deal_details Gets the status and details for a specific sales deal. ### list_companies Provides an overview and list of all company accounts in the CRM. ### list_contacts Retrieves a general listing of contacts within your HubSpot environment. ### list_deals Lists all active sales deals, showing their current stage and assigned value. ### list_hubspot_users Retrieves a list of all users who own records or are managed accounts in HubSpot. ### get_object_schema Lists all available fields (properties) for any given object type, like contacts or companies. ### search_contacts Finds specific contacts using advanced, filter-based queries. ## Prompt Examples **Prompt:** ``` Show all deals in the pipeline and the contacts associated with the highest-value one. ``` **Response:** ``` 12 active deals. Pipeline: 'Sales Pipeline'. Stages: Prospect (3), Qualified (4), Proposal (3), Negotiation (2). Top deal by value: 'Enterprise SaaS Migration' — $285,000, Stage: Negotiation, Close date: May 15, 2025, Owner: Sarah Chen. Associated contacts: 1) John Smith (CTO, john@acmecorp.com). 2) Lisa Park (VP Engineering, lisa@acmecorp.com). 3) Mike Torres (Procurement, mike@acmecorp.com). Associated company: Acme Corp (company_456, 500 employees, Enterprise segment). Total pipeline value: $892,000. Would you like to search for contacts or view the pipeline configuration? ``` **Prompt:** ``` Search for all contacts with @enterprise.com emails and create a new contact for the CEO. ``` **Response:** ``` Search results for '@enterprise.com': 4 contacts found. 1) James Rodriguez (VP Sales, james@enterprise.com). 2) Ana Müller (Director Marketing, ana@enterprise.com). 3) Chen Wei (Head of Engineering, wei@enterprise.com). 4) Sarah Johnson (HR Manager, sarah.j@enterprise.com). New contact created! Email: ceo@enterprise.com, First name: David, Last name: Williams, ID: contact_8921. Now linking to company... ✅ Associated to 'Enterprise Corp' (company_789). You now have 5 contacts for Enterprise Corp. Would you like to list companies or view deal details? ``` **Prompt:** ``` Show the sales pipelines, all HubSpot users, and the property schema for deals. ``` **Response:** ``` Sales pipelines: 2 configured. 1) 'Sales Pipeline' — 5 stages: Prospect (10%), Qualified (25%), Proposal (50%), Negotiation (75%), Closed Won (100%). 12 active deals, $892K value. 2) 'Partnership Pipeline' — 4 stages: Introduction, Evaluation, Agreement, Active Partner. 3 active deals, $150K value. HubSpot users: 8 owners. Sarah Chen (Sales), Mike Torres (Sales), Lisa Park (Marketing), James Rodriguez (CS), Ana Müller (RevOps), 3 others. Deal properties (42 total): Key fields: dealname, amount, dealstage, pipeline, closedate, hubspot_owner_id, description, deal_currency_code. Custom: contract_length, implementation_fee, annual_recurring_revenue. Would you like to create a deal or search contacts? ``` ## Capabilities ### Find and verify any record Search across contacts, companies, and deals using specific filters and metadata. ### Build or modify records Create new contacts from scratch or update details on existing company accounts. ### Establish relationships between objects Manually link related CRM entities, such as connecting a specific contact to the company they work for. ### Inspect data structure View all available fields and properties across contacts, companies, or deals to see what information is tracked. ### Track team usage List which users within your organization own specific records or manage the overall user roster. ## Use Cases ### The Quarterly Review A RevOps specialist needs to audit data integrity. Instead of running 10 separate reports, they ask the agent for a list of companies and then request details on all associated contacts that haven't been updated in six months. The agent pulls the company info, lists the contacts, and flags those needing attention. ### The Cold Start Lead A Marketing Manager identifies a target industry via external data. They use advanced search to find all contacts with that industry email domain, then immediately use create_contact to log them as leads and link the record back to the originating company. ### The Deal Closure Update A Sales Rep just had a call. Instead of logging into HubSpot and manually updating fields, they tell their agent: 'Update the deal for Acme Corp; move it to Proposal stage and add $50k in value.' The MCP handles the update instantly. ### The Missing Link A user finds a contact record but realizes they don't know which company that person belongs to. They ask the agent, 'What is this contact associated with?' and the tool returns the correct Company ID, allowing immediate association. ## Benefits - Stop switching tabs. Instead of logging into the HubSpot UI to check deal progress, you just ask your agent for 'all deals in negotiation' and get a real-time list. - Build out data quality instantly. Need to know what fields are available? Use the schema discovery tool to map out exactly what information is tracked on contacts or companies before starting a campaign. - Automate record relationships. You don't have to manually click through screens; you can tell your agent to 'link this contact to that company,' and it handles the association instantly. - Deep search capabilities. Forget simple keyword searches. Use advanced tools to filter contacts by job title, industry, or specific property values for highly targeted lists. - Full visibility across records. Get detailed breakdowns of any deal's financial status using get_deal_details, showing amounts, stages, and assignment history in one go. ## How It Works The bottom line is that it gives conversational access to every major piece of structured data in your HubSpot instance. 1. Subscribe to this MCP and enter your HubSpot Private App Access Token. 2. Connect it to your preferred AI client (Cursor, Claude, etc.). 3. Ask your agent a natural language question like, 'Find all contacts who deal with Enterprise SaaS.' The agent then executes the necessary calls to retrieve and format the data for you. ## Frequently Asked Questions **How do I find specific contacts using the search_contacts tool?** You use advanced filtering syntax, much like HubSpot's native filters. You can specify multiple criteria in one query, such as finding all contacts where 'Industry is Tech' and 'Last Name contains Smith'. **Can I update a deal stage using the get_deal_details tool?** While get_deal_details lets you read the status, you use other tools to *change* it. You must reference the specific deal ID when asking your agent to move the record. **What is the difference between list_contacts and search_contacts?** list_contacts gives you a broad overview of contacts, but search_contacts lets you narrow down that massive list using specific criteria. Use search for accuracy; use list when you just need to see who's there. **Do I have to manually link records after using this MCP?** No. You tell the agent what needs linking, and it executes the link_crm_objects tool for you, ensuring all your associated data is clean and connected. **How do I find out all the available properties when using get_object_schema?** It lists every possible property for any object type. Use this tool first to map out the schema; you'll know exactly what fields exist before trying to read or write data, preventing API errors. **What information does list_hubspot_users provide regarding my team's access?** It shows all HubSpot users and who owns the records. This is useful for auditing ownership rights and identifying which accounts are authorized to perform actions, like creating new contacts or viewing sensitive deals. **If I use the remove_contact tool, what happens to associated data?** It deletes the contact record entirely. Be careful, this action is irreversible and will break any associations with other CRM objects like companies or active deals that rely on it for context. **How do I ensure a new contact is properly linked to an existing company using link_crm_objects?** You must pass the unique IDs for both the contact and the company records. This tool formally creates the association, ensuring your AI client recognizes them as related objects in the CRM view. **Can I search for contacts using specific filters?** Yes. The `search_contacts` tool accepts a JSON array of HubSpot filters. Example: `[{"propertyName":"email","operator":"CONTAINS_TOKEN","value":"@company.com"}]`. This uses HubSpot's native search API to find contacts matching property values, date ranges, or engagement criteria. Use `get_object_schema` with 'contacts' to discover all searchable properties. **Can I link contacts to companies and deals?** Yes. Use `link_crm_objects` with the source object type and ID, target object type and ID, and the association type name. Example: link a contact to a company with `fromType='contacts', fromId='123', toType='companies', toId='456', associationType='contact_to_company'`. This creates bidirectional CRM relationships. **What type of HubSpot credential do I need?** You need a **Private App Access Token** from your HubSpot account. This is different from OAuth tokens — it provides direct API access scoped to the permissions you select when creating the Private App. The token is sent as a Bearer token in the Authorization header against `api.hubapi.com`.