HubSpot MCP Server

A powerful Model Context Protocol (MCP) server implementation for seamless HubSpot CRM integration, enabling AI assistants to interact with your HubSpot data.

Overview

This MCP server provides a comprehensive set of tools for interacting with the HubSpot CRM API, allowing AI assistants to:

• Create and manage contacts and companies in your HubSpot CRM
• Retrieve detailed company activity history and engagement timelines
• Access recent engagement data across your entire HubSpot instance
• Get lists of recently active companies and contacts
• Perform CRM operations without leaving your AI assistant interface

Why Use This MCP Server?

• Seamless AI Integration: Connect your AI assistants directly to your HubSpot CRM data
• Simplified CRM Operations: Perform common HubSpot tasks through natural language commands
• Real-time Data Access: Get up-to-date information from your HubSpot instance
• Secure Authentication: Uses HubSpot's secure API token authentication
• Extensible Design: Easily add more HubSpot API capabilities as needed

Installation

# Clone the repository
git clone https://github.com/lkm1developer/hubspot-mcp-server.git
cd hubspot-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

The server requires a HubSpot API access token. You can obtain one by:

1. Going to your HubSpot Developer Account
2. Creating a private app with the necessary scopes (contacts, companies, engagements)
3. Copying the generated access token

You can provide the token in two ways:

1. As an environment variable:

   HUBSPOT_ACCESS_TOKEN=your-access-token
   

2. As a command-line argument:

   npm start -- --access-token=your-access-token
   

For development, create a .env file in the project root to store your environment variables:

HUBSPOT_ACCESS_TOKEN=your-access-token

Usage

Starting the Server

# Start the server
npm start

# Or with a specific access token
npm start -- --access-token=your-access-token

# Run the SSE server with authentication
npx mcp-proxy-auth node dist/index.js

Implementing Authentication in SSE Server

The SSE server uses the mcp-proxy-auth package for authentication. To implement authentication:

1. Install the package:

   npm install mcp-proxy-auth
   

2. Set the AUTH_SERVER_URL environment variable to point to your API key verification endpoint:

   export AUTH_SERVER_URL=https://your-auth-server.com/verify
   

3. Run the SSE server with authentication:

   npx mcp-proxy-auth node dist/index.js
   

4. The SSE URL will be available at:

   localhost:8080/sse?apiKey=apikey
   

   Replace apikey with your actual API key for authentication.

The mcp-proxy-auth package acts as a proxy that:

• Intercepts requests to your SSE server
• Verifies API keys against your authentication server
• Only allows authenticated requests to reach your SSE endpoint

Integrating with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol. Once running, the server exposes a set of tools that can be used by compatible AI assistants to interact with your HubSpot CRM data.

Available Tools

The server exposes the following powerful HubSpot integration tools:

1. hubspot_create_contact

   • Create a new contact in HubSpot with duplicate checking
   • Parameters:
     • firstname (string, required): Contact's first name
     • lastname (string, required): Contact's last name
     • email (string, optional): Contact's email address
     • properties (object, optional): Additional contact properties like company, phone, etc.
   • Example:

     {
       "firstname": "John",
       "lastname": "Doe",
       "email": "john.doe@example.com",
       "properties": {
         "company": "Acme Inc",
         "phone": "555-123-4567",
         "jobtitle": "Software Engineer"
       }
     }
     

2. hubspot_create_company

   • Create a new company in HubSpot with duplicate checking
   • Parameters:
     • name (string, required): Company name
     • properties (object, optional): Additional company properties
   • Example:

     {
       "name": "Acme Corporation",
       "properties": {
         "domain": "acme.com",
         "industry": "Technology",
         "phone": "555-987-6543",
         "city": "San Francisco",
         "state": "CA"
       }
     }
     

3. hubspot_get_company_activity

   • Get comprehensive activity history for a specific company
   • Parameters:
     • company_id (string, required): HubSpot company ID
   • Returns detailed engagement data including emails, calls, meetings, notes, and tasks

4. hubspot_get_recent_engagements

   • Get recent engagement activities across all contacts and companies
   • Parameters:
     • days (number, optional, default: 7): Number of days to look back
     • limit (number, optional, default: 50): Maximum number of engagements to return
   • Returns a chronological list of all recent CRM activities

5. hubspot_get_active_companies

   • Get most recently active companies from HubSpot
   • Parameters:
     • limit (number, optional, default: 10): Maximum number of companies to return
   • Returns companies sorted by last modified date

6. hubspot_get_active_contacts

   • Get most recently active contacts from HubSpot
   • Parameters:
     • limit (number, optional, default: 10): Maximum number of contacts to return
   • Returns contacts sorted by last modified date

7. hubspot_update_contact

   • Update an existing contact in HubSpot (ignores if contact does not exist)
   • Parameters:
     • contact_id (string, required): HubSpot contact ID to update
     • properties (object, required): Contact properties to update
   • Example:

     {
       "contact_id": "12345",
       "properties": {
         "email": "updated.email@example.com",
         "phone": "555-987-6543",
         "jobtitle": "Senior Software Engineer"
       }
     }
     

8. hubspot_update_company

   • Update an existing company in HubSpot (ignores if company does not exist)
   • Parameters:
     • company_id (string, required): HubSpot company ID to update
     • properties (object, required): Company properties to update
   • Example:

     {
       "company_id": "67890",
       "properties": {
         "domain": "updated-domain.com",
         "phone": "555-123-4567",
         "industry": "Software",
         "city": "New York",
         "state": "NY"
       }
     }
     

Extending the Server

The server is designed to be easily extensible. To add new HubSpot API capabilities:

1. Add new methods to the HubSpotClient class in src/hubspot-client.ts
2. Register new tools in the setupToolHandlers method in src/index.ts
3. Rebuild the project with npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Keywords

HubSpot, CRM, Model Context Protocol, MCP, AI Assistant, TypeScript, API Integration, HubSpot API, CRM Integration, Contact Management, Company Management, Engagement Tracking, AI Tools