HubSpot

You can run an MCP server that connects HubSpot CRM data with your applications using multiple transports. This server implements all MCP endpoints, provides HubSpot CRUD operations, session handling, security hardening, and production-ready health and metrics, making it easy to integrate HubSpot data into your automation workflows.

How to use

Install and run the server to connect an MCP client. You can communicate over HTTP using JSON-RPC, through a streamable transport for real-time updates, or via STDIO for process-based workflows. Start by running the container with the token and transport you need, then initialize a session through the MCP transport and begin calling tools like get_contacts, create_contact, and get_deals. Use the session to manage rate limits and persistence across requests.

How to install

Prerequisites: Docker installed on your system and a HubSpot Private App Access Token.

1. Run the container (HTTP transport is shown here). This uses the HubSpot private app access token and exposes port 3000 on the host.

# GitHub Container Registry (Recommended)
docker run -d \
  --name hubspot-mcp-server \
  -p 3000:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  -e TRANSPORT=http \
  --restart unless-stopped \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

2. If you prefer Docker Hub, use this variant.

docker run -d \
  --name hubspot-mcp-server \
  -p 3000:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  -e TRANSPORT=http \
  --restart unless-stopped \
  sanketskasar/hubspot-mcp-server:latest

3. To customize ports, you can map a different host port while keeping container port at 3000.

# Use custom host port (e.g., 8080) while keeping container port as 3000
docker run -d \
  --name hubspot-mcp-server \
  -p 8080:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  --restart unless-stopped \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

Additional steps for development and testing

Verify health and basic MCP capability after startup to ensure the server is ready for client tooling.

# Health check
curl http://localhost:3000/health

# MCP capability probe
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"test"}}}'

Configuration and security notes

Configure transport, port, session management, and security settings via environment variables or compose files. The server supports multiple transports (HTTP, Streamable HTTP, STDIO) and includes session timeouts, rate limiting, and security headers to help you build robust, scalable integrations.

Core environment variables you will commonly set include HUBSPOT_PRIVATE_APP_ACCESS_TOKEN, TRANSPORT, PORT, and HOST. You can also tune rate limits and timeouts to match your workload and security requirements.

# Example Docker Compose snippet for HTTP transport
version: '3.8'
services:
  hubspot-mcp-server:
    image: ghcr.io/sanketskasar/hubspot-mcp-server:latest
    container_name: hubspot-mcp-server
    ports:
      - "3000:3000"
    environment:
      HUBSPOT_PRIVATE_APP_ACCESS_TOKEN: your_token_here
      PORT: 3000
      TRANSPORT: http
      MAX_CONNECTIONS: 100
      SESSION_TIMEOUT: 3600
      RATE_LIMIT_TOOLS: 60
      RATE_LIMIT_RESOURCES: 30
      LOG_LEVEL: info
    restart: unless-stopped

Troubleshooting tips

If the server does not start or health checks fail, verify that the HUBSPOT_PRIVATE_APP_ACCESS_TOKEN is correct and that the container has network access to HubSpot.

Check logs for hints about transport issues, port binding, or malformed configuration. Ensure you are using the correct transport mode matching your client.

Monitoring and maintenance

Monitor health and metrics endpoints to observe uptime and performance. Use container stats to watch resource usage and set up Prometheus-compatible metrics for long-term visibility.

Available tools

get_contacts

Retrieve contacts with pagination by limit, properties, and after cursor.

create_contact

Create a new contact with required email and optional properties.

update_contact

Update an existing contact by id with new properties.

search_contacts

Search contacts by a query with optional properties and limit.

get_contact_by_email

Get a contact by their email address.

get_companies

Retrieve companies with pagination by limit, properties, and after cursor.

create_company

Create a new company with required name and optional properties.

update_company

Update an existing company by id with new properties.

search_companies

Search companies by query with optional properties and limit.

get_deals

Retrieve deals with pagination by limit, properties, and after cursor.

create_deal

Create a new deal with required dealname and optional properties.

update_deal

Update an existing deal by id with new properties.

search_deals

Search deals by query with optional properties and limit.

get_associations

Get object relationships by objectId, objectType, and toObjectType.

get_engagement_history

Get activity timeline for an object by objectType and objectId.