MCP HubSpot Server

A Model Context Protocol (MCP) server that provides comprehensive HubSpot CRM integration with multi-account support and persistent credential storage. This server enables contact management, company tracking, deal pipeline management, task creation, and object associations through HubSpot's REST API.

✨ What's New in v2

🔐 Multi-Account Support

• Manage multiple HubSpot accounts simultaneously (production, sandbox, client accounts)
• Persistent credential storage using system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Account switching without restarting the MCP server
• Default account setting for new sessions
• Credential rotation support for token updates

🛡️ Enhanced Security

• Secure credential storage - no more environment variables or plain text tokens
• Automatic credential migration from legacy environment variable setup
• Graceful fallback when keychain is unavailable

🔄 Seamless Migration

• Automatic migration from v1 single-account setup
• Backward compatibility with existing environment variable configurations
• Zero configuration for existing users

Features

Account Management

• Add/remove multiple accounts with unique identifiers
• Switch between accounts dynamically during sessions
• Set default accounts for automatic selection
• Update credentials for token rotation and maintenance
• List all configured accounts with status information

Contact Management

• Create contacts with email, name, phone, company details
• Retrieve contact details by ID with optional property filtering
• Update existing contacts with new information
• Search contacts with advanced filtering and sorting capabilities

Task Management

• Create tasks with subject, status, priority, due date, and notes
• Retrieve task details by ID with optional property filtering
• Update existing tasks with new information

Object Associations

• Associate objects between contacts and tasks
• Auto-detect association types based on object types
• Support standard HubSpot associations

Property Management

• Create custom properties for any HubSpot object type (contacts, companies, deals, tickets, tasks)
• Support all field types including text, number, date, dropdown, checkbox, and more
• Configure property options for enumeration fields
• Set property groups for organization
• Advanced property settings like unique values, hidden fields, and calculation formulas

Email Template Management

• Create classic HTML email templates using HubSpot's Content API
• Custom HTML content with full control over design and layout
• Template organization with folders and categories
• Subject line configuration with default values
• Template availability settings for content creation

Installation

Install the server using Claude Code:

# Install with user scope for global availability
claude mcp add hubspot -s user -- npx @chinchillaenterprises/mcp-hubspot

# Or install with project scope for team sharing
claude mcp add hubspot -s project -- npx @chinchillaenterprises/mcp-hubspot

Quick Start

1. Add Your First Account

# Start Claude and add your HubSpot account
claude

# Add account using the MCP tools
"Add a new HubSpot account with ID 'main' and name 'Production Account' using access token 'pat-na1-...'"

2. Get Your HubSpot Access Token

1. Go to your HubSpot account
2. Navigate to Settings → Integrations → Private Apps
3. Create a new private app
4. Configure the required scopes:
   • crm.objects.contacts.read
   • crm.objects.contacts.write
   • crm.objects.tasks.read
   • crm.objects.tasks.write
   • crm.schemas.contacts.read
   • crm.schemas.contacts.write
   • crm.schemas.companies.read
   • crm.schemas.companies.write
   • crm.schemas.deals.read
   • crm.schemas.deals.write
   • crm.schemas.tasks.read
   • crm.schemas.tasks.write
   • content.read
   • content.write
5. Generate the access token and copy it

3. Start Using HubSpot

# Create a contact
"Create a contact with email [email protected] and name John Doe"

# Create a task
"Create a task with subject 'Follow up with John Doe'"

# Associate them
"Associate the contact with the task"

Multi-Account Management

Account Management Tools

add_account

Add a new HubSpot account configuration.

Parameters:

• id (required): Unique account identifier (e.g., 'main', 'sandbox', 'client-abc')
• name (required): Human-friendly account name
• accessToken (required): HubSpot access token (private app, OAuth, or API key)
• portalId (optional): HubSpot portal ID
• setAsDefault (optional): Set as default account

Example:

{
  "id": "production",
  "name": "Production HubSpot",
  "accessToken": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "portalId": "12345678",
  "setAsDefault": true
}

list_accounts

List all configured HubSpot accounts with their status information.

Returns:

{
  "accounts": [
    {
      "id": "production",
      "name": "Production HubSpot",
      "portalId": "12345678",
      "isDefault": true,
      "isActive": true
    },
    {
      "id": "sandbox",
      "name": "Sandbox Environment",
      "portalId": "87654321",
      "isDefault": false,
      "isActive": false
    }
  ],
  "activeAccountId": "production",
  "totalAccounts": 2
}

switch_account

Switch to a different HubSpot account.

Parameters:

• accountId (required): Account ID to switch to

get_active_account

Get details of the currently active account.

set_default_account

Set an account as the default for new sessions.

Parameters:

• accountId (required): Account ID to set as default

update_account

Update account credentials (useful for token rotation).

Parameters:

• accountId (required): Account ID to update
• name (optional): New account name
• accessToken (optional): New access token
• portalId (optional): New portal ID

remove_account

Remove a HubSpot account configuration.

Parameters:

• accountId (required): Account ID to remove

HubSpot Operations

Contact Tools

hubspot_create_contact

Create a new contact in HubSpot.

Parameters:

• email (required): Contact email address (serves as unique identifier)
• firstname (optional): First name
• lastname (optional): Last name
• phone (optional): Phone number
• company (optional): Company name
• website (optional): Website URL
• properties (optional): Additional custom properties

Example:

{
  "email": "[email protected]",
  "firstname": "John",
  "lastname": "Doe",
  "phone": "+1-555-123-4567",
  "company": "Acme Corp"
}

hubspot_get_contact

Retrieve contact details by ID.

Parameters:

• contact_id (required): HubSpot contact ID
• properties (optional): Array of specific properties to retrieve

hubspot_update_contact

Update an existing contact.

Parameters:

• contact_id (required): HubSpot contact ID
• properties (required): Object with properties to update

hubspot_search_contacts

Search contacts with advanced filtering.

Parameters:

• query (optional): Search query text
• filters (optional): Array of property filters
• sorts (optional): Array of sort criteria
• limit (optional): Number of results (1-100, default: 10)

Example:

{
  "filters": [
    {
      "propertyName": "email",
      "operator": "CONTAINS_TOKEN",
      "value": "@example.com"
    }
  ],
  "sorts": [
    {
      "propertyName": "createdate",
      "direction": "DESCENDING"
    }
  ],
  "limit": 20
}

Task Tools

hubspot_create_task

Create a new task in HubSpot.

Parameters:

• subject (required): Task subject/title
• status (optional): Task status (NOT_STARTED, IN_PROGRESS, COMPLETED, WAITING, DEFERRED)
• priority (optional): Task priority (LOW, MEDIUM, HIGH)
• due_date (optional): Due date (YYYY-MM-DD)
• notes (optional): Task notes/description
• properties (optional): Additional custom properties

hubspot_get_task

Retrieve task details by ID.

Parameters:

• task_id (required): HubSpot task ID
• properties (optional): Array of specific properties to retrieve

hubspot_update_task

Update an existing task.

Parameters:

• task_id (required): HubSpot task ID
• properties (required): Object with properties to update

Association Tools

hubspot_associate_objects

Create associations between HubSpot objects.

Parameters:

• from_object_type (required): Source object type (contact, task)
• from_object_id (required): Source object ID
• to_object_type (required): Target object type (contact, task)
• to_object_id (required): Target object ID
• association_type (optional): Association type (auto-detected if not provided)

Example:

{
  "from_object_type": "contact",
  "from_object_id": "12345",
  "to_object_type": "task",
  "to_object_id": "67890"
}

Property Tools

hubspot_create_property

Create a custom property for HubSpot objects.

Parameters:

• object_type (required): Object type to create property for (contact, company, deal, ticket, task)
• name (required): Internal name for the property (cannot be changed after creation)
• label (required): Display label for the property
• type (required): Field type (text, textarea, number, date, datetime, enumeration, bool, radio, checkbox, email, phone_number, html, calculation_equation)
• group_name (required): Property group to add this property to
• description (optional): Description of the property
• options (optional): Array of options for enumeration, radio, or checkbox fields
  • label (required): Display label for the option
  • value (required): Internal value for the option
  • description (optional): Option description
  • display_order (optional): Order in which to display the option
• display_order (optional): Order in which to display the property
• has_unique_value (optional): Whether the property value must be unique (default: false)
• hidden (optional): Whether the property is hidden (default: false)
• form_field (optional): Whether the property can be used in forms (default: true)
• calculation_formula (optional): Formula for calculation properties
• external_options (optional): Whether options are managed externally (default: false)

Example:

// Create a dropdown property for contact preferred language
{
  "object_type": "contact",
  "name": "preferred_language",
  "label": "Preferred Language",
  "type": "enumeration",
  "group_name": "contactinformation",
  "description": "Customer's preferred language for communication",
  "options": [
    {
      "label": "English",
      "value": "en",
      "display_order": 0
    },
    {
      "label": "Spanish",
      "value": "es",
      "display_order": 1
    },
    {
      "label": "French",
      "value": "fr",
      "display_order": 2
    }
  ]
}

// Create a number property for task priority score
{
  "object_type": "task",
  "name": "priority_score",
  "label": "Priority Score",
  "type": "number",
  "group_name": "taskdetails",
  "description": "Numeric priority score from 1-100",
  "display_order": 5
}

Email Template Tools

hubspot_create_email_template

Create a classic HTML email template in HubSpot.

Parameters:

• name (required): Template name/filename (e.g., 'welcome-email.html')
• label (required): Display label for the template
• html_content (required): HTML content of the email template
• subject (optional): Default subject line for the email template
• folder_id (optional): Folder ID to organize the template
• category_id (optional): Template category ID (default: 1 for email template)
• description (optional): Description of the template
• is_available_for_new_content (optional): Whether template is available for new content (default: true)
• template_type (optional): Type of template (default: "EMAIL")

Example:

// Create a welcome email template
{
  "name": "welcome-email",
  "label": "Welcome Email Template",
  "subject": "Welcome to Our Service!",
  "html_content": `
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <title>Welcome Email</title>
      <style>
        body { font-family: Arial, sans-serif; margin: 0; padding: 20px; }
        .container { max-width: 600px; margin: 0 auto; }
        .header { background-color: #007BFF; color: white; padding: 20px; text-align: center; }
        .content { padding: 20px; line-height: 1.6; }
        .footer { background-color: #f8f9fa; padding: 15px; text-align: center; font-size: 12px; }
      </style>
    </head>
    <body>
      <div class="container">
        <div class="header">
          <h1>Welcome to Our Service!</h1>
        </div>
        <div class="content">
          <p>Hi {{contact.firstname}},</p>
          <p>Thank you for joining our service. We're excited to have you on board!</p>
          <p>Your account has been successfully created and you can now access all our features.</p>
          <p>If you have any questions, feel free to reach out to our support team.</p>
          <p>Best regards,<br>The Team</p>
        </div>
        <div class="footer">
          <p>&copy; 2024 Our Company. All rights reserved.</p>
        </div>
      </div>
    </body>
    </html>
  `,
  "description": "Welcome email template for new users"
}

// Create a newsletter template
{
  "name": "monthly-newsletter",
  "label": "Monthly Newsletter",
  "subject": "Your Monthly Update",
  "html_content": `
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <title>Monthly Newsletter</title>
      <style>
        body { font-family: Georgia, serif; margin: 0; padding: 20px; background-color: #f4f4f4; }
        .newsletter { max-width: 700px; margin: 0 auto; background: white; }
        .header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; }
        .article { padding: 25px; border-bottom: 1px solid #eee; }
        .cta-button { background-color: #28a745; color: white; padding: 12px 24px; text-decoration: none; border-radius: 5px; display: inline-block; margin: 15px 0; }
      </style>
    </head>
    <body>
      <div class="newsletter">
        <div class="header">
          <h1>Monthly Newsletter</h1>
          <p>Your latest updates and insights</p>
        </div>
        <div class="article">
          <h2>This Month's Highlights</h2>
          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
          <a href="#" class="cta-button">Read More</a>
        </div>
        <div class="article">
          <h2>Featured Content</h2>
          <p>Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...</p>
        </div>
      </div>
    </body>
    </html>
  `,
  "folder_id": 12345,
  "description": "Monthly newsletter template with featured content sections"
}

Usage Examples

Multi-Account Setup

// Add production account
{
  "tool": "add_account",
  "args": {
    "id": "production",
    "name": "Production HubSpot",
    "accessToken": "pat-na1-prod-token-here",
    "setAsDefault": true
  }
}

// Add sandbox account
{
  "tool": "add_account",
  "args": {
    "id": "sandbox",
    "name": "Sandbox Environment",
    "accessToken": "pat-na1-sandbox-token-here"
  }
}

// Switch to sandbox for testing
{
  "tool": "switch_account",
  "args": {
    "accountId": "sandbox"
  }
}

// Create test contact in sandbox
{
  "tool": "hubspot_create_contact",
  "args": {
    "email": "[email protected]",
    "firstname": "Test",
    "lastname": "User"
  }
}

// Switch back to production
{
  "tool": "switch_account",
  "args": {
    "accountId": "production"
  }
}

Basic Workflow: Create Contact with Task

// 1. Create a contact
{
  "tool": "hubspot_create_contact",
  "args": {
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Smith",
    "phone": "+1-555-987-6543"
  }
}

// 2. Create a task
{
  "tool": "hubspot_create_task",
  "args": {
    "subject": "Follow up with Jane Smith",
    "status": "NOT_STARTED",
    "priority": "HIGH",
    "due_date": "2024-12-31"
  }
}

// 3. Associate contact with task
{
  "tool": "hubspot_associate_objects",
  "args": {
    "from_object_type": "contact",
    "from_object_id": "contact_id_from_step_1",
    "to_object_type": "task",
    "to_object_id": "task_id_from_step_2"
  }
}

Migration from v1

Automatic Migration

If you're upgrading from v1, the server will automatically detect your existing HUBSPOT_ACCESS_TOKEN environment variable and:

1. Create a default account with your existing credentials
2. Store the credentials securely in your system keychain
3. Set it as the active account
4. Continue working seamlessly

Manual Migration

If you prefer to set up accounts manually:

1. Remove the old environment variable (optional)
2. Add your accounts using the add_account tool
3. Set your preferred default using set_default_account

Error Handling

The server provides comprehensive error handling for common scenarios:

• Authentication errors: Invalid or expired access tokens
• Permission errors: Insufficient scopes or permissions
• Validation errors: Invalid input parameters
• Rate limiting: HubSpot API rate limit exceeded
• Not found errors: Requested resources don't exist
• Account errors: Account not found, invalid credentials

All errors include descriptive messages to help diagnose issues.

Rate Limiting

HubSpot has the following rate limits:

• Burst limit: 190 requests per 10 seconds
• Daily limit: 1,000,000 requests per day

The server automatically handles rate limiting errors and provides helpful error messages when limits are exceeded.

Credential Storage

Keychain Support

The server uses the keytar library to securely store credentials in:

• macOS: Keychain Access
• Windows: Windows Credential Manager
• Linux: Secret Service API (GNOME Keyring, KDE Wallet)

Fallback Mode

If keychain is unavailable, the server:

• Warns about disabled persistence
• Continues to work with in-memory credentials
• Falls back to environment variables for single-account setup

Testing

This server is designed for live testing with your HubSpot account. Make sure you have:

1. A valid HubSpot account with appropriate permissions
2. A Private App Access Token with required scopes
3. Test data or a willingness to create test records

Local Development Testing

# 1. Install dependencies
cd mcp-hubspot
npm install

# 2. Build the server
npm run build

# 3. Add server locally for testing
claude mcp add hubspot-test -s user -- node $(pwd)/dist/index.js

# 4. Start Claude and test
claude
# Try: "Add a HubSpot account with ID 'test' and name 'Test Account'"

Development

Prerequisites

• Node.js 18+
• TypeScript
• HubSpot account with Private App Access Token

Setup

git clone <repository>
cd mcp-hubspot
npm install
npm run build

Building

npm run build          # Build once
npm run dev           # Build and watch for changes

Contributing

1. Follow the existing code structure and patterns
2. Add comprehensive error handling for new features
3. Update this README with new tools and examples
4. Test thoroughly with live HubSpot data
5. Follow the ChillMCP conventions for consistency

License

MIT License - see LICENSE file for details.

Note: This MCP server provides direct access to your HubSpot CRM data. Always test with non-production data first and ensure you have appropriate backups before making bulk changes.