# HubSpot MCP Server

The HubSpot MCP Server is a Model Context Protocol implementation that provides standardized access to the HubSpot CRM API. This server enables AI applications and agents to interact with HubSpot's customer relationship management platform through a unified interface. Built on the MCP SDK, it exposes HubSpot's comprehensive CRM capabilities including contacts, companies, deals, engagements, and communication preferences.

The server implements over 100 tools covering all major HubSpot CRM operations with type-safe parameter validation using Zod schemas. It supports both standard STDIO transport for local MCP clients and streamable HTTP transport for remote deployments. Authentication is handled via HubSpot access tokens, and the server includes built-in telemetry for monitoring usage patterns. The implementation follows HubSpot's API v3 and v4 specifications with support for batch operations, advanced search filters, and association management.

## API Reference and Code Examples

### Create a Company

Create a new company record in HubSpot with validated properties and optional associations to other CRM objects.

```typescript
// Using the MCP tool directly
const result = await mcpClient.callTool("crm_create_company", {
  properties: {
    name: "Acme Corporation",
    domain: "acme.com",
    website: "https://www.acme.com",
    industry: "Technology",
    numberofemployees: 250,
    annualrevenue: 5000000,
    city: "San Francisco",
    state: "CA",
    country: "United States",
    phone: "+1-555-0123",
    lifecyclestage: "customer"
  },
  associations: [
    {
      to: { id: "12345" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 1
        }
      ]
    }
  ]
});

// Response
{
  "content": [{
    "type": "text",
    "text": "{\"id\":\"67890\",\"properties\":{\"name\":\"Acme Corporation\",\"domain\":\"acme.com\",\"createdate\":\"2025-01-10T10:30:00Z\"},\"createdAt\":\"2025-01-10T10:30:00Z\",\"updatedAt\":\"2025-01-10T10:30:00Z\"}"
  }]
}
```

### Search Contacts with Filters

Search for contacts using advanced filter groups with multiple criteria, sorting, and pagination.

```typescript
// Search for contacts in a specific lifecycle stage with recent activity
const searchResult = await mcpClient.callTool("crm_search_contacts", {
  filterGroups: [
    {
      filters: [
        {
          propertyName: "lifecyclestage",
          operator: "EQ",
          value: "marketingqualifiedlead"
        },
        {
          propertyName: "lastmodifieddate",
          operator: "GT",
          value: "2025-01-01T00:00:00Z"
        }
      ]
    }
  ],
  properties: ["email", "firstname", "lastname", "phone", "company"],
  limit: 50,
  sorts: [
    {
      propertyName: "lastmodifieddate",
      direction: "DESCENDING"
    }
  ]
});

// Response includes paginated results
{
  "content": [{
    "type": "text",
    "text": "{\"total\":125,\"results\":[{\"id\":\"101\",\"properties\":{\"email\":\"john@example.com\",\"firstname\":\"John\",\"lastname\":\"Doe\"}},{\"id\":\"102\",\"properties\":{\"email\":\"jane@example.com\",\"firstname\":\"Jane\",\"lastname\":\"Smith\"}}],\"paging\":{\"next\":{\"after\":\"50\"}}}"
  }]
}
```

### Batch Create Multiple Contacts

Create multiple contact records in a single API request for efficient bulk operations.

```typescript
// Batch create contacts with error handling
const batchResult = await mcpClient.callTool("crm_batch_create_contacts", {
  inputs: [
    {
      properties: {
        email: "alice@example.com",
        firstname: "Alice",
        lastname: "Johnson",
        phone: "+1-555-1111",
        lifecyclestage: "lead"
      }
    },
    {
      properties: {
        email: "bob@example.com",
        firstname: "Bob",
        lastname: "Williams",
        phone: "+1-555-2222",
        lifecyclestage: "subscriber"
      },
      associations: [
        {
          to: { id: "67890" },
          types: [
            {
              associationCategory: "HUBSPOT_DEFINED",
              associationTypeId: 279
            }
          ]
        }
      ]
    }
  ]
});

// Response includes all created records
{
  "content": [{
    "type": "text",
    "text": "{\"status\":\"COMPLETE\",\"results\":[{\"id\":\"201\",\"properties\":{\"email\":\"alice@example.com\"}},{\"id\":\"202\",\"properties\":{\"email\":\"bob@example.com\"}}]}"
  }]
}
```

### Create Meeting Engagement

Create a meeting engagement record with scheduling details and associate it with contacts and deals.

```typescript
// Create a scheduled meeting with associations
const meetingResult = await mcpClient.callTool("meetings_create", {
  properties: {
    hs_timestamp: "2025-01-15T14:00:00Z",
    hs_meeting_title: "Q1 Strategy Review",
    hs_meeting_body: "Quarterly business review to discuss goals and metrics",
    hs_meeting_location: "Conference Room A",
    hs_meeting_start_time: "2025-01-15T14:00:00Z",
    hs_meeting_end_time: "2025-01-15T15:00:00Z",
    hs_meeting_outcome: "SCHEDULED",
    hubspot_owner_id: "54321"
  },
  associations: [
    {
      to: { id: "101" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 200
        }
      ]
    },
    {
      to: { id: "5001" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 206
        }
      ]
    }
  ]
});

// Response
{
  "content": [{
    "type": "text",
    "text": "{\"id\":\"3001\",\"properties\":{\"hs_meeting_title\":\"Q1 Strategy Review\",\"hs_meeting_outcome\":\"SCHEDULED\"},\"createdAt\":\"2025-01-10T10:35:00Z\"}"
  }]
}
```

### Manage Object Associations

Create associations between CRM objects using the v4 associations API with specific association types.

```typescript
// Associate a contact with a company
const associationResult = await mcpClient.callTool("crm_create_association", {
  fromObjectType: "contacts",
  toObjectType: "companies",
  fromObjectId: "101",
  toObjectId: "67890",
  associationTypes: [
    {
      associationCategory: "HUBSPOT_DEFINED",
      associationTypeId: 1
    }
  ]
});

// Get all associations for a contact
const getAssociations = await mcpClient.callTool("crm_get_associations", {
  fromObjectType: "contacts",
  toObjectType: "deals",
  fromObjectId: "101",
  limit: 100
});

// Batch create multiple associations
const batchAssociations = await mcpClient.callTool("crm_batch_create_associations", {
  fromObjectType: "contacts",
  toObjectType: "deals",
  inputs: [
    {
      from: { id: "101" },
      to: { id: "5001" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 3
        }
      ]
    },
    {
      from: { id: "102" },
      to: { id: "5002" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 3
        }
      ]
    }
  ]
});
```

### Create and Manage Tasks

Create task engagements with priorities, due dates, and associations to track follow-up activities.

```typescript
// Create a high-priority task
const taskResult = await mcpClient.callTool("tasks_create", {
  properties: {
    hs_task_body: "Follow up on proposal discussion and address technical questions",
    hs_task_subject: "Follow-up: Technical Proposal",
    hs_task_priority: "HIGH",
    hs_task_status: "NOT_STARTED",
    hs_task_type: "CALL",
    hs_task_due_date: "2025-01-12T17:00:00Z",
    hs_timestamp: "2025-01-10T10:40:00Z",
    hubspot_owner_id: "54321"
  },
  associations: [
    {
      to: { id: "101" },
      types: [
        {
          associationCategory: "HUBSPOT_DEFINED",
          associationTypeId: 204
        }
      ]
    }
  ]
});

// Update task status
const updateTask = await mcpClient.callTool("tasks_update", {
  taskId: "4001",
  properties: {
    hs_task_status: "IN_PROGRESS",
    hs_task_body: "Follow up on proposal discussion and address technical questions. UPDATE: Scheduled call for tomorrow."
  }
});
```

### Search Objects with Advanced Filters

Use the generic search endpoint to query any CRM object type with complex filter logic.

```typescript
// Search deals with multiple filter conditions
const dealSearch = await mcpClient.callTool("crm_search_objects", {
  objectType: "deals",
  filterGroups: [
    {
      filters: [
        {
          propertyName: "dealstage",
          operator: "IN",
          value: ["presentationscheduled", "decisionmakerboughtin", "contractsent"]
        },
        {
          propertyName: "amount",
          operator: "GTE",
          value: 10000
        },
        {
          propertyName: "closedate",
          operator: "LTE",
          value: "2025-03-31T23:59:59Z"
        }
      ]
    }
  ],
  properties: ["dealname", "amount", "dealstage", "closedate", "pipeline"],
  limit: 100,
  sorts: [
    {
      propertyName: "amount",
      direction: "DESCENDING"
    }
  ]
});
```

### Manage Communication Preferences

Update email subscription preferences for contacts with proper legal basis documentation.

```typescript
// Get contact's communication preferences
const getPreferences = await mcpClient.callTool("communications_get_preferences", {
  contactId: "101"
});

// Update specific subscription status
const updatePreferences = await mcpClient.callTool("communications_update_preferences", {
  contactId: "101",
  subscriptionId: "12345",
  preferences: {
    subscriptionId: "12345",
    status: "SUBSCRIBED",
    legalBasis: "CONSENT_WITH_NOTICE",
    legalBasisExplanation: "User opted in via website form on 2025-01-10"
  }
});

// Bulk update subscription status for multiple contacts
const bulkUpdate = await mcpClient.callTool("communications_update_subscription_status", {
  subscriptionId: "12345",
  updates: [
    {
      contactId: "101",
      status: "SUBSCRIBED",
      legalBasis: "CONSENT_WITH_NOTICE"
    },
    {
      contactId: "102",
      status: "UNSUBSCRIBED"
    }
  ]
});
```

### Create Custom Properties

Define custom properties for CRM objects to extend the standard HubSpot schema.

```typescript
// Create a custom company property
const propertyResult = await mcpClient.callTool("crm_create_company_property", {
  name: "technology_stack",
  label: "Technology Stack",
  type: "enumeration",
  fieldType: "select",
  groupName: "companyinformation",
  description: "Primary technology platform used by the company",
  options: [
    {
      label: "AWS",
      value: "aws",
      displayOrder: 1,
      hidden: false
    },
    {
      label: "Azure",
      value: "azure",
      displayOrder: 2,
      hidden: false
    },
    {
      label: "Google Cloud",
      value: "gcp",
      displayOrder: 3,
      hidden: false
    }
  ],
  displayOrder: 10,
  hasUniqueValue: false,
  hidden: false,
  formField: true
});

// Get all available properties
const getProperties = await mcpClient.callTool("crm_get_company_properties", {
  archived: false
});
```

### Batch Operations for Efficiency

Perform bulk operations on multiple CRM objects with a single API request to reduce latency.

```typescript
// Batch update multiple companies
const batchUpdateResult = await mcpClient.callTool("crm_batch_update_objects", {
  objectType: "companies",
  inputs: [
    {
      id: "67890",
      properties: {
        lifecyclestage: "customer",
        annualrevenue: 5500000
      }
    },
    {
      id: "67891",
      properties: {
        lifecyclestage: "opportunity",
        numberofemployees: 150
      }
    }
  ]
});

// Batch read specific objects by ID
const batchReadResult = await mcpClient.callTool("crm_batch_read_objects", {
  objectType: "contacts",
  objectIds: ["101", "102", "103", "104"],
  properties: ["email", "firstname", "lastname", "lifecyclestage", "lastmodifieddate"]
});

// Batch archive (delete) multiple objects
const batchArchiveResult = await mcpClient.callTool("crm_batch_archive_objects", {
  objectType: "deals",
  objectIds: ["5001", "5002", "5003"]
});
```

### Product Management

Create and manage product catalog items with pricing and SKU information.

```typescript
// Create a product
const productResult = await mcpClient.callTool("products_create", {
  properties: {
    name: "Enterprise Plan",
    description: "Full-featured enterprise subscription with premium support",
    price: 999.00,
    sku: "ENT-001",
    hs_product_type: "Subscription",
    hs_recurring_billing_period: "Monthly"
  }
});

// Search products by criteria
const productSearch = await mcpClient.callTool("products_search", {
  filterGroups: [
    {
      filters: [
        {
          propertyName: "price",
          operator: "GTE",
          value: 500
        },
        {
          propertyName: "hs_product_type",
          operator: "EQ",
          value: "Subscription"
        }
      ]
    }
  ],
  properties: ["name", "price", "sku", "description"],
  limit: 50
});

// Batch update product prices
const productBatchUpdate = await mcpClient.callTool("products_batch_update", {
  inputs: [
    {
      id: "8001",
      properties: { price: 1099.00 }
    },
    {
      id: "8002",
      properties: { price: 1999.00 }
    }
  ]
});
```

## Use Cases and Integration Patterns

The HubSpot MCP Server enables AI agents and applications to perform comprehensive CRM operations programmatically. Primary use cases include building AI-powered sales assistants that can create and update contact records, schedule meetings, and track deal progression through the pipeline. Marketing automation scenarios leverage the communication preferences tools to manage email subscriptions while maintaining GDPR compliance through proper legal basis documentation. The batch operation tools are particularly valuable for data synchronization tasks, enabling efficient bulk updates when integrating HubSpot with other business systems or performing periodic data maintenance operations.

Integration patterns typically involve using the search tools to query CRM data based on specific criteria, then performing create or update operations based on the results. The association management capabilities enable building relationship graphs between contacts, companies, deals, and engagements to maintain data integrity. For custom workflows, the server supports extending HubSpot's schema through custom properties and leveraging the comprehensive engagement tools (calls, emails, meetings, notes, tasks) to log all customer interactions. The stateless design with Bearer token authentication makes it straightforward to deploy as a microservice, while the dual transport support (STDIO and HTTP) provides flexibility for both local MCP client integrations and cloud-based agent platforms.