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

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

• 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

# 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

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

# 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

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

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.

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"
       }
     }

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

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

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