HubSpot MCP Server

How to use

Once the MCP server is running, you can issue natural language commands through your MCP client to create or update HubSpot records, fetch company activity, pull recent engagements, and retrieve lists of active contacts and companies. Use the HTTP endpoint when you want a remote connection to the MCP server, or use the local stdio configuration to run the server directly from your environment. Authentication is handled via a HubSpot access token and an optional API-key verification step for the SSE endpoint.

How to install

# 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 and security

You must provide a HubSpot API access token to enable API calls. Obtain a token by creating a private app in your HubSpot Developer account with the required scopes (contacts, companies, engagements). You can supply the token in two ways. Set an environment variable HUBSPOT_ACCESS_TOKEN with your token, or pass the token as a command-line argument when starting the server.

# Environment variable (preferred in development)
HUBSPOT_ACCESS_TOKEN=your-access-token

# Start the server with the token via CLI
npm start -- --access-token=your-access-token

Starting the server

# Start the server with the default configuration
npm start

# Start the server with a specific access token
npm start -- --access-token=your-access-token

# Run the SSE server with authentication (if you enable the proxy Auth flow)
npx mcp-proxy-auth node dist/index.js

How authentication via SSE works

To enable authenticated SSE connections, configure the authentication endpoint and run the proxy helper. The proxy validates incoming API keys before allowing access to the SSE endpoint, which ensures only authorized clients can stream HubSpot data.

# Example environment for authentication proxy
export AUTH_SERVER_URL=https://your-auth-server.com/verify

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

# SSE endpoint (authenticated)
http://localhost:8080/sse?apiKey=apikey

Available tools and endpoints

The server exposes a set of HubSpot capabilities you can invoke from your MCP client, including creating and updating contacts and companies, retrieving company activity, and listing recent engagements and active records.

hubspot_create_contact

Create a new HubSpot contact with optional duplicate checking and properties such as company, phone, and job title.

hubspot_create_company

Create a new HubSpot company with optional properties like domain, industry, phone, city, and state.

hubspot_get_company_activity

Retrieve a comprehensive activity history for a specific HubSpot company, including emails, calls, meetings, notes, and tasks.

hubspot_get_recent_engagements

Fetch recent engagement activities across contacts and companies with optional days look-back and limit.

hubspot_get_active_companies

List the most recently active companies sorted by last modified date.

hubspot_get_active_contacts

List the most recently active contacts sorted by last modified date.

hubspot_update_contact

Update an existing HubSpot contact by ID with new properties, ignoring if the contact does not exist.

hubspot_update_company

Update an existing HubSpot company by ID with new properties, ignoring if the company does not exist.