mcpengine/servers/hubspot

HubSpot MCP Server

Model Context Protocol (MCP) server for HubSpot CRM API v3. Provides comprehensive access to HubSpot CRM objects, marketing tools, CMS, and analytics.

Features

• CRM Objects: Contacts, Companies, Deals, Tickets, Line Items, Products, Quotes
• Associations: Manage relationships between objects
• Marketing: Email campaigns, forms, lists, workflows
• CMS: Blog posts, pages, HubDB tables
• Engagements: Notes, calls, emails, meetings, tasks
• Pipelines & Stages: Deal and ticket pipeline management
• Search API: Advanced filtering and search across all objects
• Batch Operations: Efficient bulk create/update/archive
• Rate Limiting: Automatic retry with exponential backoff
• Pagination: Automatic handling of cursor-based pagination

Installation

npm install
npm run build

Configuration

Create a .env file (see .env.example):

HUBSPOT_ACCESS_TOKEN=your-private-app-token-here

Getting a HubSpot Access Token

1. Go to your HubSpot account settings
2. Navigate to Integrations → Private Apps
3. Click Create a private app
4. Configure the required scopes:
   • crm.objects.contacts.read / crm.objects.contacts.write
   • crm.objects.companies.read / crm.objects.companies.write
   • crm.objects.deals.read / crm.objects.deals.write
   • crm.objects.owners.read
   • Additional scopes based on your needs
5. Copy the generated access token

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/path/to/hubspot/dist/main.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Available Tools

Contacts

• hubspot_contacts_list - List all contacts with pagination
• hubspot_contacts_get - Get a contact by ID
• hubspot_contacts_create - Create a new contact
• hubspot_contacts_update - Update contact properties
• hubspot_contacts_search - Search contacts with filters

Companies

• hubspot_companies_list - List all companies
• hubspot_companies_get - Get a company by ID
• hubspot_companies_create - Create a new company

Deals

• hubspot_deals_list - List all deals
• hubspot_deals_get - Get a deal by ID
• hubspot_deals_create - Create a new deal

Tickets

• hubspot_tickets_list - List all tickets
• hubspot_tickets_create - Create a new ticket

Associations

• hubspot_associations_get - Get associations for an object
• hubspot_associations_create - Create an association between objects

Pipelines

• hubspot_pipelines_list - List pipelines for an object type

Owners

• hubspot_owners_list - List all owners in the account

Properties

• hubspot_properties_list - List properties for an object type

Architecture

Core Components

1. src/types/index.ts - Comprehensive TypeScript type definitions for all HubSpot entities
2. src/clients/hubspot.ts - API client with retry logic, rate limiting, and pagination
3. src/server.ts - MCP server implementation with lazy-loaded tool modules
4. src/main.ts - Entry point with environment validation and graceful shutdown

API Client Features

• Authentication: Bearer token (Private App or OAuth)
• Rate Limiting: Automatic handling of 429 responses with retry-after headers
• Retry Logic: Exponential backoff for transient failures (max 3 retries)
• Pagination: Automatic cursor-based pagination (HubSpot uses after cursor)
• Batch Operations: Efficient bulk operations for create/update/archive
• Type Safety: Full TypeScript type definitions for all API entities

HubSpot API Limits

• Free/Starter: 10 requests/second
• Professional/Enterprise: Higher limits based on tier
• Search API: Up to 10,000 results per search
• Batch API: Up to 100 objects per batch request

Error Handling

The server provides structured error responses:

{
  content: [{
    type: 'text',
    text: 'Error: HubSpot API Error: {message} ({status}) [{correlationId}]'
  }],
  isError: true
}

Development

Type Safety

All HubSpot entities use branded types for IDs:

type ContactId = string & { readonly __brand: 'ContactId' };
type CompanyId = string & { readonly __brand: 'CompanyId' };

Adding New Tools

1. Add tool definition in src/server.ts → ListToolsRequestSchema handler
2. Add routing in handleToolCall method
3. Implement handler method (or lazy-load from separate module)

Testing

npm test  # (tests not yet implemented)

Type Checking

npx tsc --noEmit

Resources

• HubSpot API Documentation
• HubSpot CRM API v3
• Model Context Protocol

License

MIT

Support

For issues and feature requests, please open an issue on GitHub.