Merge Unified's HubSpot integration Merge Agent Handler's HubSpot MCP server

Connect your AI Agents to HubSpot in minutes

Merge lets you securely connect your agents to HubSpot and thousands of tools instantly

Start building for free

Read docs

HubSpot

Learn more about Merge Agent Handler

Available tools

get_deal_associations

Get all associations (emails, notes, calls, meetings, tasks) for a specific deal. Use this to find activities related to a deal, such as 'get all emails for the Acme Markets deal' or 'list notes associated with deal 12345'. Returns the IDs and metadata of associated objects which can then be fetched individually for full details.

list_deal_notes

Get all notes for a deal with full content and HubSpot UI URLs. Returns note details with clickable links to view in HubSpot. Use for 'show notes on Acme deal with links'.

list_deal_calls

Get all calls for a deal with full details and HubSpot UI URLs. Returns call info (duration, outcome, notes) with clickable links. Use for 'show calls on Acme deal with links'.

list_deal_meetings

Get all meetings for a deal with full details and HubSpot UI URLs. Returns meeting info (title, attendees, time) with clickable links. Use for 'show meetings on Acme deal with links'.

list_deal_tasks

Get all tasks for a deal with full details and HubSpot UI URLs. Returns task info (status, due date, assignee) with clickable links. Use for 'show tasks on Acme deal with links'.

list_deal_emails

Get all emails for a deal with full content and HubSpot UI URLs. Returns email info (subject, body, sender) with clickable links. Use for 'show emails on Acme deal with links'.

list_deal_activities

Get ALL activities (emails, notes, calls, meetings, tasks) for a deal with HubSpot UI URLs. Returns complete timeline with clickable links. Use for 'show everything on Acme deal with links'.

get_company_associations

Get all associations (emails, notes, calls, meetings, tasks) for a specific company. Use this to find activities related to a company, such as 'get all emails for Acme Corp' or 'list notes associated with company 12345'. Returns the IDs and metadata of associated objects.

list_company_notes

Get all notes for a company with full content and HubSpot UI URLs. Returns note details with clickable links to view in HubSpot. Use for 'show notes on Acme Corp with links'.

list_company_calls

Get all calls for a company with full details and HubSpot UI URLs. Returns call info (duration, outcome, notes) with clickable links. Use for 'show calls on Acme Corp with links'.

list_company_meetings

Get all meetings for a company with full details and HubSpot UI URLs. Returns meeting info (title, attendees, time) with clickable links. Use for 'show meetings on Acme Corp with links'.

list_company_tasks

Get all tasks for a company with full details and HubSpot UI URLs. Returns task info (status, due date, assignee) with clickable links. Use for 'show tasks on Acme Corp with links'.

list_company_emails

Get all emails for a company with full content and HubSpot UI URLs. Returns email info (subject, body, sender) with clickable links. Use for 'show emails on Acme Corp with links'.

list_company_activities

Get ALL activities (emails, notes, calls, meetings, tasks) for a company with HubSpot UI URLs. Returns complete timeline with clickable links. Use for 'show everything on Acme Corp with links'.

get_contact_associations

Get all associations (emails, notes, calls, meetings, tasks) for a specific contact. Use this to find activities related to a contact, such as 'get all emails for John Doe' or 'list notes associated with contact 12345'. Returns the IDs and metadata of associated objects.

list_contact_notes

Get all notes for a contact with full content and HubSpot UI URLs. Returns note details with clickable links to view in HubSpot. Use for 'show notes on John Doe with links'.

list_contact_calls

Get all calls for a contact with full details and HubSpot UI URLs. Returns call info (duration, outcome, notes) with clickable links. Use for 'show calls on John Doe with links'.

list_contact_meetings

Get all meetings for a contact with full details and HubSpot UI URLs. Returns meeting info (title, attendees, time) with clickable links. Use for 'show meetings on John Doe with links'.

list_contact_tasks

Get all tasks for a contact with full details and HubSpot UI URLs. Returns task info (status, due date, assignee) with clickable links. Use for 'show tasks on John Doe with links'.

list_contact_emails

Get all emails for a contact with full content and HubSpot UI URLs. Returns email info (subject, body, sender) with clickable links. Use for 'show emails on John Doe with links'.

list_contact_activities

Get ALL activities (emails, notes, calls, meetings, tasks) for a contact with HubSpot UI URLs. Returns complete timeline with clickable links. Use for 'show everything on John Doe with links'.

batch_update_objects

Update many CRM records of one object type in a single call. Pass all records as inputs=[{"id":"123","properties":{...}}]; they are auto-batched in groups of 100, so use this instead of many single updates to avoid rate limits. Custom objects (e.g. contracts) must be addressed by their type id like '2-3465404', not the bare name (use listcustomobjects to find it).

batch_read_objects

Read many CRM records of one object type by ID in a single call. Pass all ids as inputs=[{"id":"123"}]; they are auto-batched in groups of 100. Custom objects must be addressed by their type id like '2-3465404', not the bare name (use listcustomobjects to find it).

batch_create_objects

Create many CRM records of one object type in a single call. Pass all records as inputs=[{"properties":{...}}]; they are auto-batched in groups of 100, so use this instead of many single creates to avoid rate limits. Custom objects must be addressed by their type id like '2-3465404', not the bare name (use listcustomobjects to find it).

create_call

Log a call engagement in HubSpot CRM. Associate with contacts, companies, deals, or tickets using format: associations=[{"id": "123", "type": "contact"}]. Returns engagement URL with parent context.

get_call

Get a call by ID. Optional: pass parentObjectType and parentObjectId (e.g., parentObjectType='contact', parentObjectId='123') to get URL with parent context.

update_call

Update a call's details. Optional: pass parentObjectType and parentObjectId to get URL with parent context.

delete_call

Delete a call log from HubSpot

list_calls

List call logs with pagination and filtering

search_calls

Search calls by direction, status, duration, or date. Use for finding specific call logs.

create_company

Create a new company with name, domain, industry, and location details

get_company

Retrieve a company by its ID or unique property with specified properties, associations, and history

update_company

Update properties and information for an existing company

delete_company

Delete a company from HubSpot (cannot be undone)

list_companies

List companies with pagination and optional property filtering

search_companies

Search companies with filters (name, domain, industry, location, size), sorting, and text query. Use filters array for property conditions with operators (EQ, CONTAINS_TOKEN, IN). Supports free text query search. Returns up to 100 companies per page with pagination.

create_contact

Create a new contact with email, name, phone, company, and lifecycle stage

get_contact

Get a contact by ID or email with properties and engagement history

update_contact

Update properties and information for an existing contact

delete_contact

Delete a contact from HubSpot (cannot be undone)

list_contacts

List contacts with pagination and optional property filtering

search_contacts

Search contacts with filters (email, name, company, lifecyclestage), sorting, and text query. Use filters array for property conditions with operators (EQ, GT, IN, CONTAINS_TOKEN). Supports free text query search. Returns up to 100 contacts per page with pagination.

batch_create_contacts

Create up to 100 contacts in a single batch request

batch_update_contacts

Update up to 100 contacts in a single batch request

batch_read_contacts

Get up to 100 contacts by IDs in a single batch request

create_deal

Create a new sales deal with name, amount, pipeline stage, and owner

get_deal

Get a deal by ID with pipeline stage and associated contacts/companies

update_deal

Update properties and details for an existing deal

delete_deal

Delete a deal from HubSpot (cannot be undone)

list_deals

List deals with pagination and filtering by pipeline, stage, or owner

search_deals

Search deals with filters (amount, stage, closedate, owner), sorting, and text query. Use filters array for property conditions with operators (EQ, GT, IN, BETWEEN). Supports free text query search. Returns up to 100 deals per page with pagination.

create_email

Log an email engagement in HubSpot CRM. Record sent/received emails with subject, body, direction, status, attachments. Associate with contacts, companies, deals, or tickets using format: associations=[{"id": "123", "type": "contact"}]. Returns engagement URL.

get_email

Retrieve a specific email engagement by ID from HubSpot CRM. Returns complete email details including subject, body, sender/recipient information, direction, status, timestamps, and associated CRM records. Optional: pass parentObjectType and parentObjectId (e.g., parentObjectType='contact', parentObjectId='123') to get URL with parent context.

update_email

Update an existing email engagement's properties in HubSpot CRM. Modify email subject, body, status, direction, or other email properties. Optional: pass parentObjectType and parentObjectId to get URL with parent context.

delete_email

Delete an email engagement from HubSpot CRM (moves to recycling bin). Use this to remove incorrect email logs, clean up test data, delete duplicate email entries, or remove emails that were logged in error. Deleted emails can be restored from the recycling bin.

list_emails

List email engagements from HubSpot CRM with pagination and property filtering. Retrieve up to 100 emails per request with support for cursor-based pagination. Specify which email properties to return, include archived emails, and navigate through large result sets. Use this to browse email history, review recent communications, or export email data.

search_emails

Search email engagements in HubSpot CRM using filters, text queries, and sorting. Find emails by subject keywords, sender/recipient, date ranges, email status, direction, or any email property. Supports complex filtering with AND/OR logic, full-text search, custom sorting, and pagination. Use this to locate specific emails, filter by criteria, or find emails matching patterns.

create_meeting

Log a meeting engagement in HubSpot CRM. Associate with contacts, companies, deals, or tickets using format: associations=[{"id": "123", "type": "contact"}]. Returns engagement URL with parent context.

get_meeting

Get a meeting by ID. Optional: pass parentObjectType and parentObjectId (e.g., parentObjectType='contact', parentObjectId='123') to get URL with parent context.

update_meeting

Update a meeting's details. Optional: pass parentObjectType and parentObjectId to get URL with parent context.

delete_meeting

Delete a meeting from HubSpot

list_meetings

List meetings with pagination and filtering

search_meetings

Search meetings by title, date, outcome, or location. Use for finding specific meetings.

create_note

Create a note engagement in HubSpot CRM. Pass the note text as content (e.g. content='Met with customer'). Associate with contacts, companies, deals, or tickets using associations=[{"id": "123", "type": "contact"}]. Returns engagement URL with parent context.

get_note

Get a note by ID. Optional: pass parentObjectType and parentObjectId (e.g., parentObjectType='contact', parentObjectId='123') to get URL with parent context.

update_note

Update a note's content or properties. Pass the new note text as content (e.g. content='Revised summary'). Optional: pass parentObjectType and parentObjectId to get URL with parent context.

delete_note

Delete a note from HubSpot

list_notes

List notes with pagination and filtering

search_notes

Search notes by content, filters, or associated objects. Use for finding specific notes by keywords or properties.

list_owners

Retrieve a list of all owners (users) in the HubSpot account with their contact information, team assignments, and permissions. Used for assigning ownership of contacts, companies, deals, and tickets.

get_owner

Retrieve detailed information about a specific owner (user) in HubSpot using their owner ID. Returns owner details including name, email, teams, and activity status for ownership assignment.

list_deal_properties

List all available deal properties including custom fields with their types, descriptions, valid values, and metadata. Essential for discovering what fields can be used in search filters, updates, and deal creation. Returns property names, data types, field types (text, number, date, dropdown, etc.), available options for dropdowns, and whether fields are required, read-only, or calculated.

list_contact_properties

List all available contact properties including custom fields with their types, descriptions, valid values, and metadata. Essential for discovering what fields can be used in search filters, updates, and contact creation. Returns property names, data types, field types (text, number, date, dropdown, etc.), available options for dropdowns, and whether fields are required, read-only, or calculated.

list_company_properties

List all available company properties including custom fields with their types, descriptions, valid values, and metadata. Essential for discovering what fields can be used in search filters, updates, and company creation. Returns property names, data types, field types (text, number, date, dropdown, etc.), available options for dropdowns, and whether fields are required, read-only, or calculated.

list_custom_objects

List all custom objects in HubSpot with their required properties, searchable fields and schema info, plus the objecttypeid (e.g. '2-3465404') the batch* tools need. This is the only way to discover required fields in HubSpot. Full property and association definitions are omitted by default; set includeproperties or include_associations to true only if you need them.

create_task

Create a task engagement in HubSpot CRM. Associate with contacts, companies, deals, or tickets using format: associations=[{"id": "123", "type": "contact"}]. Returns engagement URL with parent context.

get_task

Get a task by ID. Optional: pass parentObjectType and parentObjectId (e.g., parentObjectType='contact', parentObjectId='123') to get URL with parent context.

update_task

Update a task's details or mark it complete. Optional: pass parentObjectType and parentObjectId to get URL with parent context.

delete_task

Delete a task from HubSpot

list_tasks

List tasks with pagination and filtering

search_tasks

Search tasks by status, priority, due date, or assignee. Use for finding specific tasks.

create_ticket

Create a support ticket with subject (required), priority, category, and owner

get_ticket

Retrieve a ticket by its ID, optionally selecting which properties to return

update_ticket

Update properties and status for an existing ticket

delete_ticket

Delete a ticket from HubSpot (cannot be undone)

list_tickets

List support tickets with filtering by status, priority, or owner

search_tickets

Search tickets by subject, status, priority, category, or date ranges

validate_credential

Validate HubSpot credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's HubSpot MCP server

Who is the HubSpot MCP server for?

It can be used for endless AI assistants, agents, and third-party AI/automation apps.

How can I use the HubSpot MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Automated contact enrichment: Your agent can automatically enrich HubSpot contacts with additional data when new leads are created, such as company information, social profiles, and engagement history

Real-time deal updates: As sales reps engage with prospects, your agent can automatically update deal properties in HubSpot, including deal stage, amount, expected close date, and custom fields

Marketing intelligence: Your agent can help marketing teams create custom reports on campaign performance via HubSpot data. For example, a marketing manager can ask for a conversion rate report, and the agent can use fields like campaign names, lead sources, and conversion metrics to create them

Email sequence optimization: Your agent can generate personalized email sequences by pulling data from the relevant HubSpot contact and deal records and by leveraging similar successful sequences from other prospects

What are popular tools for HubSpot’s MCP server?

Here are just a few popular tools across data types:

Deals

<code class="blog_inline-code">get_deal_associations</code>
<code class="blog_inline-code">list_deal_notes</code>
<code class="blog_inline-code">list_deal_calls</code>
<code class="blog_inline-code">list_deal_activities</code>

Companies

<code class="blog_inline-code">list_company_tasks</code>
<code class="blog_inline-code">get_company_associations</code>
<code class="blog_inline-code">list_company_emails</code>

Tasks

<code class="blog_inline-code">get_task</code>
<code class="blog_inline-code">update_task</code>
<code class="blog_inline-code">delete_task</code>
<code class="blog_inline-code">list_task</code>

Can I set custom security rules for HubSpot tool calls in Merge Agent Handler?

Yes, you can apply custom security rules to HubSpot tool calls. Merge's security gateway and data loss prevention (DLP) applies to all connectors, including HubSpot.

Here are just a few examples:

Credit card numbers: Block any HubSpot contact or deal updates that contain credit card numbers in fields like notes or descriptions

Social security numbers: Prevent your agents from adding SSNs to HubSpot contact records or deal properties

Email addresses: Redact email addresses when agents retrieve or search HubSpot contacts, so they only see masked versions (e.g., j*@merge.dev)

Phone numbers: Automatically redact phone numbers from HubSpot contact details when agents retrieve them

API keys and tokens: Block agents from posting authentication credentials or access tokens in HubSpot deal notes or contact properties

Internal account IDs: Mask sensitive customer identifiers when agents read or update HubSpot records to prevent cross-account information leakage

You can configure these rules to block, redact, or log sensitive data, and they apply across all tool calls made to HubSpot through Agent Handler.

What makes Merge Agent Handler’s HubSpot MCP server better than alternative HubSpot MCP servers?

Here are some of the top reasons:

‍Enterprise-grade authentication handling: Merge manages OAuth, credential lifecycle, and secure connector onboarding via Merge Link. This lets your agent avoid handling tokens directly

‍Security gateway and data loss prevention: Merge scans all HubSpot tool inputs/outputs for sensitive data (e.g., PII, credentials) and can block, redact, or mask content‍

Real-time observability and audit trail: Agent Handler logs every tool call and every underlying API request, and provides fully searchable logs ‍

Tool Pack configuration and multi-connector orchestration: Merge allows you to bundle HubSpot with other systems (Salesforce, Jira, Slack, etc.) with per-agent permission controls

How can I add tools to Merge Agent Handler’s HubSpot MCP server?

You can customize or expand the HubSpot connector using Connector Studio and Tool Packs. Here's how:

In Connector Studio

Log into the Agent Handler dashboard.
Navigate to Connector Studio in the sidebar.
Select the HubSpot connector.
From there, you can customize the connector.

In the Tool Pack configuration

Create or select a Tool Pack (Navigate to "Tool Packs" in the sidebar).
Add the HubSpot connector to your Tool Pack by clicking "Add Connector".
Enable or disable specific HubSpot tools as needed for your use case.
Save your changes. The HubSpot connector and its tools are now available in your Tool Pack.