HubSpot Integration
Manage contacts, companies, tickets and conversations in HubSpot
The HubSpot MCP server enables seamless integration with your HubSpot CRM. Manage contacts, companies, tickets and access conversations - all directly from your assistant.
Setup
Prerequisites
- A HubSpot account (Professional or Enterprise)
- Super Admin permissions or the App Marketplace Access permission in your HubSpot account
- Organization Admin permissions in meinGPT (to configure integrations)
Not sure if you have the right permissions? Ask your HubSpot admin — you can check your permissions under Settings → Users & Teams.
Step-by-Step Guide
Create a Private App in HubSpot
- Log into your HubSpot account
- Click the gear icon (⚙️ Settings) in the top-right corner
- In the left sidebar, navigate to Integrations → Private Apps
- Click Create a private app
Fill in the basic information:
- App name: e.g.
meinGPT Integration(freely chosen — only used for internal reference) - Description: e.g.
Connection between meinGPT and HubSpot CRM(optional) - Logo: optional, helps with identification
Configure Scopes (Permissions)
Switch to the Scopes tab in the creation dialog. This is where you define what HubSpot data meinGPT can access.
Use the search field to find and enable the required scopes.
Option A: Minimal Read-Only Access
If you only want to read data from HubSpot (no creating/editing):
| Scope | Description |
|---|---|
crm.objects.contacts.read | Read contacts |
crm.objects.companies.read | Read companies |
crm.objects.deals.read | Read deals |
crm.objects.owners.read | Read owner information |
conversations.read | Read conversations |
files | Read/search files |
Option B: Full Access (recommended)
For full functionality including creating and editing CRM objects:
| Scope | Description |
|---|---|
crm.objects.contacts.read | Read contacts |
crm.objects.contacts.write | Create/edit contacts |
crm.objects.companies.read | Read companies |
crm.objects.companies.write | Create/edit companies |
crm.objects.deals.read | Read deals |
crm.objects.deals.write | Create/edit deals |
crm.objects.owners.read | Read owner information |
conversations.read | Read conversations |
files | Read/search files |
Optional Scopes
Depending on your needs, you can additionally enable:
| Scope | Description |
|---|---|
tickets | Ticket management |
sales-email-read | Read email objects (for generic CRM search) |
You can always add more scopes later. Feel free to start with fewer permissions and expand as needed — you'll just need to generate a new token.
Create the App and Copy the Access Token
- Click Create app
- Confirm in the dialog that you want to create the app
- Your Access Token is now displayed — copy it immediately!
Important: The Access Token is only shown once! Copy it now and save it somewhere safe. If you lose the token, you'll need to generate a new one under Private Apps → Your App → Auth.
Connect HubSpot in meinGPT
- Open meinGPT and navigate to Settings → Integrations (you need org admin permissions)
- Find HubSpot in the connector list and enable the integration
- Paste the copied Access Token into the HubSpot Access Token field
- The connection is automatically tested — a green checkmark confirms everything is working
Enable HubSpot for Assistants
- Open the Assistant Editor for the desired assistant
- Scroll to the Tools section
- Enable the HubSpot tool
- Optional: Configure method-level access (e.g. enable only read methods)
Your assistant can now access HubSpot data! Try it with something like: "Show me the last 5 active contacts from HubSpot"
Scope Profiles (When do you need what?)
| Use case | Required scopes |
|---|---|
| Base CRM Read (owners + search/retrieve contacts/companies/deals) | crm.objects.owners.read, crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read |
| CRM Write (create contact/company/deal) | crm.objects.contacts.write, crm.objects.companies.write, crm.objects.deals.write |
Conversations (hubspot_get_recent_conversations) | conversations.read |
Files (hubspot_search_files, hubspot_get_file) | files |
Ticket workflows (hubspot_get_tickets, ticket pipelines/threads) | tickets (account/feature dependent) |
| Generic search for additional objects | object-specific scopes from HubSpot endpoint docs (for emails: sales-email-read) |
Method-to-Scope Mapping
| Method | Scopes |
|---|---|
hubspot_get_owners | crm.objects.owners.read |
hubspot_get_active_contacts | crm.objects.contacts.read |
hubspot_create_contact | crm.objects.contacts.write |
hubspot_get_active_companies | crm.objects.companies.read |
hubspot_create_company | crm.objects.companies.write |
hubspot_get_deals | crm.objects.deals.read |
hubspot_create_deal | crm.objects.deals.write |
hubspot_search_crm_objects | object-specific scopes from endpoint docs (for emails: sales-email-read) |
hubspot_retrieve_crm_object | object-specific scopes from endpoint docs |
hubspot_get_recent_conversations | conversations.read |
hubspot_search_files | files |
hubspot_get_file | files |
hubspot_get_tickets, hubspot_get_ticket_conversation_threads, ticket pipelines | tickets (HubSpot setup dependent) |
Main Features
Company Management
hubspot_create_company: Creates a new company with name, domain and other propertieshubspot_get_company_activity: Shows the activity history of a companyhubspot_get_active_companies: Lists recently active companies
Contact Management
hubspot_create_contact: Creates a new contact with email, name and other detailshubspot_get_active_contacts: Shows recently active contacts
Generic Search & Retrieve
hubspot_search_crm_objects: Generic CRM search (contacts, companies, deals, notes, tasks, calls, meetings, emails)hubspot_retrieve_crm_object: Retrieve one CRM object by ID including optional associations
File Access
hubspot_search_files: Search HubSpot files metadatahubspot_get_file: Retrieve file metadata and signed URL
Conversations
hubspot_get_recent_conversations: Retrieves recent conversation threads with messages- Supports filtering by time period
- Includes complete message history
Ticket Management
hubspot_get_tickets: Lists tickets with extensive filtering options- Filter by status, priority, pipeline
- Sorting and pagination
hubspot_get_ticket_conversation_threads: Shows all conversations for a specific ticket
Usage Examples
Create New Contact
Create a new contact in HubSpot:
- Email: max.mustermann@example.com
- First Name: Max
- Last Name: Mustermann
- Company: Example GmbHRetrieve Company with Activities
Show me the recent activities of the company "Example GmbH" in HubSpotDisplay Open Support Tickets
List all open support tickets with high prioritySearch Conversations
Show me all conversations from the last 7 daysRetrieve CRM Object
Find the latest deal for company "Example GmbH" and return the deal details by IDSearch and Load Files
Search HubSpot files for "invoice" and return the signed download URL of the latest resultBest Practices
Security
- Token Management: Never store your access token in code
- Regular Rotation: Renew tokens regularly
- Minimal Permissions: Only activate required scopes
- Activity Monitoring: Regularly check app logs in HubSpot
Performance
- Use pagination for large data sets
- Implement caching for frequently accessed data
- Observe HubSpot's API rate limits (100 requests/10 seconds)
Data Quality
- Validate email addresses before creating contacts
- Use meaningful ticket descriptions
- Keep company and contact data up to date
Troubleshooting
Token Not Accepted (401 Unauthorized)
- Make sure you copied the token correctly (no leading/trailing spaces)
- Check if the token is still valid — under Settings → Integrations → Private Apps in HubSpot
- If the token was revoked, generate a new one in your Private App
Missing Permissions (403 Forbidden)
- A specific HubSpot function returns a 403 error? You're probably missing a scope.
- Open your Private App in HubSpot and check the enabled scopes
- Add the missing scope and generate a new token
- Update the token in meinGPT under Settings → Integrations
Token Lost or Expired
- In HubSpot, navigate to Settings → Integrations → Private Apps
- Select your app and go to the Auth tab
- Click Show token or generate a new one
- Update the token in meinGPT
Rate Limit (429 Too Many Requests)
- HubSpot allows 100 requests per 10 seconds
- Reduce the number of concurrent requests
- Use pagination and batch operations where possible
Additional Resources
Revoking Token
If you need to revoke access:
Navigate to: Settings → Integrations → Private Apps
Select your app
Click "Delete App" or generate a new token
Revoking or renewing the token immediately interrupts all existing integrations.