HubSpot MCP Server
Enables AI clients to seamlessly interact with HubSpot CRM data and take HubSpot actions through the Model Context Protocol (MCP). This skill provides comprehensive access to HubSpot's CRM objects, properties, associations, engagements, and workflows.
What This Skill Does
This skill connects your AI assistant to HubSpot's CRM platform, allowing you to:
Search and retrieve CRM records (contacts, companies, deals, tickets)Create and update CRM objects in batchesManage associations between CRM recordsAdd engagements (notes, tasks) to recordsAccess workflow informationRetrieve property schemas and definitionsGenerate HubSpot UI links for direct accessSetup Instructions
Prerequisites
1. **Create a HubSpot Private App:**
- Navigate to Settings > Integrations > Private Apps in your HubSpot account
- Click "Create private app"
- Name your app and configure required scopes (consider starting with read-only scopes)
- Click "Create app"
- Copy the generated access token
2. **Install Node.js and npm:**
- Visit https://nodejs.org/en/download to install Node.js (includes npm)
Configuration
Add the following configuration to your MCP client:
**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": ["-y", "@hubspot/mcp-server"],
"env": {
"PRIVATE_APP_ACCESS_TOKEN": "<your-private-app-access-token>"
}
}
}
}
```
**For Cursor** (`.cursor/mcp.json` in your project):
```json
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": ["-y", "@hubspot/mcp-server"],
"env": {
"PRIVATE_APP_ACCESS_TOKEN": "<your-private-app-access-token>"
}
}
}
}
```
Replace `<your-private-app-access-token>` with your actual HubSpot private app access token.
Restart your MCP client after saving the configuration.
Usage Instructions
Step 1: Verify Authentication
Before performing any operations, verify your connection:
**Prompt:** "Authenticate my HubSpot connection and show me my account details."
This uses the `hubspot-get-user-details` tool to confirm your token is valid.
Step 2: Explore Available Data
Understand what CRM objects and properties are available:
**Prompts:**
"Show me all custom object schemas in my HubSpot account.""List all properties for the Contact object in HubSpot.""Get the definition for the 'lifecyclestage' property."Step 3: Search and Retrieve CRM Data
Use natural language to query your CRM:
**Example Prompts:**
"Get me the latest update about Acme Inc. from my HubSpot account.""Summarize all deals in the 'Decision maker bought in' stage with deal value > $1000.""Show me the last five tickets created for Alex Smith.""List all contacts at example.com domain.""Find companies created in the last 30 days."Step 4: Create and Update Records
Create new CRM records or update existing ones:
**Example Prompts:**
"Create a new contact [email protected] for Acme Inc. in my HubSpot account.""Update the address for John Smith to 123 Main St, San Francisco, CA.""Create a company called 'Beta Corp' with website betacorp.com.""Update deal 'Q1 Enterprise Deal' to stage 'Closed Won'."Step 5: Manage Associations
Connect related CRM records:
**Example Prompts:**
"Associate John Smith with Acme Inc. as a company in my HubSpot account.""List all associated contacts and their roles for Acme Inc.""Show me all deals associated with contact [email protected].""What are the valid association types between contacts and companies?"Step 6: Add Engagements
Create tasks and notes:
**Example Prompts:**
"Add a task to send a thank-you note to [email protected] in my HubSpot account.""Create a note for Acme Inc. saying 'Initial discovery call went well'.""List my overdue HubSpot tasks.""Add a task to follow up with John Smith next Monday."Step 7: Access Workflows
Retrieve workflow information:
**Example Prompts:**
"List all workflows in my HubSpot account.""Show me details about the 'Lead Nurture' workflow.""What enrollment criteria does my onboarding workflow use?"Step 8: Generate UI Links
Get direct links to HubSpot records:
**Prompt:** "Generate a link to open contact [email protected] in the HubSpot UI."
Available Tools
The HubSpot MCP server provides these tools:
**OAuth:**
`hubspot-get-user-details` - Authenticate and get account information**Objects:**
`hubspot-list-objects` - Retrieve paginated lists of CRM records`hubspot-search-objects` - Perform filtered searches with complex criteria`hubspot-batch-create-objects` - Create multiple records in one call`hubspot-batch-update-objects` - Update multiple records in one call`hubspot-batch-read-objects` - Retrieve multiple records by ID`hubspot-get-schemas` - Get custom object schemas**Properties:**
`hubspot-list-properties` - List all properties for an object type`hubspot-get-property` - Get detailed property definition`hubspot-create-property` - Create custom properties`hubspot-update-property` - Update property settings**Associations:**
`hubspot-batch-create-associations` - Create relationships between records`hubspot-list-associations` - Retrieve existing associations`hubspot-get-association-definitions` - Get valid association types**Engagements:**
`hubspot-create-engagement` - Create notes or tasks`hubspot-get-engagement` - Retrieve engagement details`hubspot-update-engagement` - Update existing engagement**Workflows:**
`hubspot-list-workflows` - List all workflows`hubspot-get-workflow` - Get workflow details**Links:**
`hubspot-generate-feedback-link` - Generate feedback link for MCP tools`hubspot-get-link` - Generate HubSpot UI URLsImportant Notes
**Beta Status:** This MCP server is in beta and subject to HubSpot's Early Adopter Program terms (https://legal.hubspot.com/early-adopter-program)**Scopes:** Ensure your private app has appropriate scopes for the operations you need. Start with read-only scopes for testing.**Rate Limits:** HubSpot API has rate limits. Batch operations are recommended for bulk actions.**Feedback:** Use the prompt "Provide feedback for HubSpot MCP tools" to submit feedback directly to HubSpot.**Documentation:** Visit https://developers.hubspot.com/mcp for official documentation and updates.Troubleshooting
If tools are not appearing:
1. Verify the configuration file syntax is correct
2. Ensure the private app access token is valid and properly set
3. Restart your MCP client completely
4. Check that Node.js and npm are installed correctly
5. Review the MCP client documentation:
- Claude Desktop: https://modelcontextprotocol.io/quickstart/user
- Cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers