HubSpot MCP Server

🚀 A complete Model Context Protocol (MCP) server for HubSpot CRM integration, implementing all 21 MCP protocol endpoints with multi-transport support (HTTP, Streamable HTTP, STDIO) and flexible port configuration.

✨ Features

Complete MCP Protocol: All 21 endpoints (initialize, tools, resources, prompts, notifications, logging)
Multi-Transport Support: HTTP JSON-RPC, Streamable HTTP (SSE), STDIO for process-based communication
Comprehensive HubSpot Integration: 15+ tools for contacts, companies, deals with full CRUD operations
Session Management: UUID-based sessions with timeout and rate limiting
Production Ready: Health checks, metrics, structured logging, graceful shutdown
Security Hardened: OWASP compliance, non-root execution, security headers
Multi-Architecture: Docker images for AMD64 and ARM64 platforms
Flexible Port Configuration: Configurable ports via build args and runtime environment variables
Advanced Session Management: Cookie and header-based session persistence for HTTP requests

📦 Available Images

Registry	Image	Command
GitHub Container Registry	`ghcr.io/sanketskasar/hubspot-mcp-server:latest`	`docker pull ghcr.io/sanketskasar/hubspot-mcp-server:latest`
Docker Hub	`sanketskasar/hubspot-mcp-server:latest`	`docker pull sanketskasar/hubspot-mcp-server:latest`

🚀 Quick Start

Prerequisites

Docker installed on your system
HubSpot Private App Access Token (Setup Guide)

1. Run Container

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

Docker Hub:

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

Custom Port Configuration:

# 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

# Use custom container port (requires rebuild)
docker build --build-arg EXPOSE_PORT=8080 -t hubspot-mcp-server:custom .
docker run -d \
  --name hubspot-mcp-server \
  -p 8080:8080 \
  -e PORT=8080 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  hubspot-mcp-server:custom

2. Verify Installation

# Check health
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","uptime":...,"version":"1.0.0","sessions":0}

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

🔧 Transport Protocols

HTTP Transport (Default)

Standard JSON-RPC 2.0 over HTTP:

docker run -d -p 3000:3000 \
  -e TRANSPORT=http \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

Streamable HTTP Transport

Server-sent events for real-time updates:

docker run -d -p 3000:3000 \
  -e TRANSPORT=streamable-http \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

# Connect to stream
curl -N -H "Accept: text/event-stream" http://localhost:3000/mcp/stream

STDIO Transport

Process-based communication:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
docker run --rm -i \
  -e TRANSPORT=stdio \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

⚙️ Configuration

Environment Variables

# Required Configuration
HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here

# Transport Configuration
TRANSPORT=http                    # http, streamable-http, stdio
PORT=3000
HOST=0.0.0.0

# Session Management
MAX_CONNECTIONS=100
SESSION_TIMEOUT=3600              # seconds

# Rate Limiting
RATE_LIMIT_TOOLS=60              # requests per minute
RATE_LIMIT_RESOURCES=30          # requests per minute  
MAX_CONCURRENT_REQUESTS=10       # per session

# Security
CORS_ORIGIN=*                    # "*", specific domain, or comma-separated
MAX_REQUEST_SIZE=10485760        # 10MB

# Operational
LOG_LEVEL=info                   # debug, info, warn, error
CONNECTION_TIMEOUT=30000         # milliseconds
GRACEFUL_SHUTDOWN_TIMEOUT=10000  # milliseconds

Docker Compose

Basic Configuration:

version: '3.8'
services:
  hubspot-mcp-server:
    image: ghcr.io/sanketskasar/hubspot-mcp-server:latest
    container_name: hubspot-mcp-server
    ports:
      - "${HOST_PORT:-3000}:${CONTAINER_PORT:-3000}"
    environment:
      HUBSPOT_PRIVATE_APP_ACCESS_TOKEN: ${HUBSPOT_PRIVATE_APP_ACCESS_TOKEN}
      PORT: ${CONTAINER_PORT:-3000}
      TRANSPORT: http
      MAX_CONNECTIONS: 100
      SESSION_TIMEOUT: 3600
      RATE_LIMIT_TOOLS: 60
      RATE_LIMIT_RESOURCES: 30
      LOG_LEVEL: info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${CONTAINER_PORT:-3000}/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Custom Port Configuration:

# Run on custom ports
HOST_PORT=8080 CONTAINER_PORT=3000 docker-compose up -d

# Or set in .env file:
# HOST_PORT=8080
# CONTAINER_PORT=3000

🔧 Session Management

The server provides advanced session management for HTTP requests to maintain state across multiple API calls:

Session Creation

Sessions are automatically created on the first request and tracked via:

X-Session-ID Header: Primary method for API clients
mcp-session Cookie: Browser-friendly session persistence
Request Body Parameter: Alternative session identification

Session Persistence Examples

Using Headers (Recommended for API clients):

# 1. Initialize and get session ID
response=$(curl -s -i -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}}')

# Extract session ID from X-Session-ID header
session_id=$(echo "$response" | grep -i "x-session-id" | cut -d' ' -f2 | tr -d '\r')

# 2. Use session ID in subsequent requests
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: $session_id" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

Using Authorization Bearer (Alternative method):

# Use session ID as Bearer token
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $session_id" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}'

Using Cookies (Browser-compatible):

# Save cookies and reuse them
curl -c cookies.txt -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}}'

# Subsequent requests with cookies
curl -b cookies.txt -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "resources/list", "params": {}}'

Session Features

Automatic Creation: Sessions created transparently on first request
Multiple Persistence Methods: Headers, cookies, and body parameters
aiohttp.ClientSession Compatible: Optimized for Python HTTP clients
Authorization Bearer Support: Alternative session identification method
Configurable Timeout: Sessions expire after SESSION_TIMEOUT seconds
Reconnection Support: SSE transport allows session reconnection
Rate Limiting: Per-session rate limits for tools and resources
Security: SameSite protection, configurable secure flag for HTTPS

🔑 HubSpot Setup

Step 1: Create Private App

Go to HubSpot Settings → Integrations → Private Apps
Click "Create a private app"
Configure required scopes:

Scope	Purpose
`crm.objects.contacts.read`	Read contact information
`crm.objects.contacts.write`	Create and update contacts
`crm.objects.companies.read`	Read company information
`crm.objects.companies.write`	Create and update companies
`crm.objects.deals.read`	Read deal information
`crm.objects.deals.write`	Create and update deals
`crm.objects.owners.read`	Read owner/sales rep information

Step 2: Generate Token

Go to Auth tab
Copy the Access Token (starts with pat-...)
⚠️ Keep this token secure!

Step 3: Test Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.hubapi.com/crm/v3/objects/contacts?limit=1"

🛠️ Available Tools

The server implements 15+ HubSpot CRM tools through the MCP protocol:

Contact Management

Tool	Description	Parameters
`get_contacts`	Retrieve contacts with pagination	`limit`, `properties`, `after`
`create_contact`	Create new contact	`email` (required), other properties
`update_contact`	Update existing contact	`id`, `properties`
`search_contacts`	Search contacts by query	`query`, `properties`, `limit`
`get_contact_by_email`	Get contact by email	`email`

Company Management

Tool	Description	Parameters
`get_companies`	Retrieve companies with pagination	`limit`, `properties`, `after`
`create_company`	Create new company	`name` (required), other properties
`update_company`	Update existing company	`id`, `properties`
`search_companies`	Search companies by query	`query`, `properties`, `limit`

Deal Management

Tool	Description	Parameters
`get_deals`	Retrieve deals with pagination	`limit`, `properties`, `after`
`create_deal`	Create new deal	`dealname` (required), other properties
`update_deal`	Update existing deal	`id`, `properties`
`search_deals`	Search deals by query	`query`, `properties`, `limit`

Relationship & Activity Tools

Tool	Description	Parameters
`get_associations`	Get object relationships	`objectId`, `objectType`, `toObjectType`
`get_engagement_history`	Get activity timeline	`objectId`, `objectType`

📊 Resources

8+ Live Resources Available:

hubspot://contacts - Live contacts database
hubspot://companies - Live companies database
hubspot://deals - Live deals pipeline
hubspot://properties/contacts - Contact property schema
hubspot://properties/companies - Company property schema
hubspot://properties/deals - Deal property schema
hubspot://pipelines/deals - Deal pipeline configuration
hubspot://owners - Sales rep/owner information

💡 Prompts

5+ Ready-to-Use Prompts:

analyze_pipeline - Deal pipeline analysis and optimization
contact_research - Deep contact and company research
lead_scoring - Lead qualification and scoring
email_templates - HubSpot email template generation
meeting_prep - Pre-meeting research and preparation

📈 Monitoring & Health

Health Endpoints

Endpoint	Purpose	Response
`GET /health`	Basic health check	Health status and uptime
`GET /ready`	Readiness probe	Application readiness
`GET /metrics`	Prometheus metrics	Performance metrics
`GET /status`	Detailed status	Comprehensive server status

Example Usage

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

# List available tools
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"sessionId":"session-id"}}'

# Get contacts
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"get_contacts",
      "arguments":{"limit":5},
      "sessionId":"session-id"
    }
  }'

🔒 Security Features

Non-root execution - Container runs as unprivileged user
Security hardening - Read-only filesystem, dropped capabilities
OWASP headers - Complete security header implementation
Session management - UUID-based sessions with timeouts
Rate limiting - Configurable per-session rate limits
Input validation - Comprehensive parameter validation

🛠️ Development

Local Development

git clone https://github.com/SanketSKasar/HubSpot-MCP-Server.git
cd HubSpot-MCP-Server

# Install dependencies
npm install

# Set up environment
cp env.example .env
# Edit .env with your HubSpot token

# Run with different transports
npm start -- --transport http
npm start -- --transport streamable-http  
npm start -- --transport stdio

# Run tests
npm test

# Build Docker image
docker build -t hubspot-mcp-server .

Command Line Options

node src/server.js --help

Options:
  --transport, -t    Transport protocol (http|streamable-http|stdio)
  --port, -p         Port to listen on (default: 3000)
  --host, -h         Host to bind to (default: 0.0.0.0)
  --log-level        Logging level (debug|info|warn|error)
  --max-connections  Maximum concurrent connections
  --session-timeout  Session timeout in seconds

📊 Performance

Resource Requirements

Environment	CPU	Memory	Concurrent Sessions
Minimum	0.25 cores	256MB	10
Recommended	0.5 cores	512MB	50
High Load	1+ cores	1GB+	100+

Monitoring

# Container metrics
docker stats hubspot-mcp-server

# Application metrics  
curl http://localhost:3000/metrics

# Performance testing
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/health

🚀 Building Multi-Architecture Images

# Setup buildx for multi-arch
docker buildx create --name multiarch --use

# Build for multiple architectures with default port
docker buildx build \
  --build-arg EXPOSE_PORT=3000 \
  --platform linux/amd64,linux/arm64 \
  --tag ghcr.io/sanketskasar/hubspot-mcp-server:latest \
  --tag sanketskasar/hubspot-mcp-server:latest \
  --push .

# Build with custom port configuration
docker buildx build \
  --build-arg EXPOSE_PORT=8080 \
  --platform linux/amd64,linux/arm64 \
  --tag your-registry/hubspot-mcp-server:custom-port \
  --push .

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure all tests pass: npm test
Submit a pull request

📜 License

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

Model Context Protocol - Official MCP specification
HubSpot API Documentation - HubSpot CRM API
MCP Protocol Specification - Technical MCP details

📋 Latest Updates - Version 1.0.0

🎉 Production Release Features

✅ Complete Multi-Transport Support: HTTP, Streamable HTTP (SSE), and STDIO protocols
✅ Flexible Port Configuration: Build-time and runtime port customization
✅ Enhanced Session Management: UUID-based sessions with comprehensive rate limiting
✅ Multi-Architecture Images: Native support for AMD64 and ARM64 platforms
✅ Production Hardening: OWASP security compliance and comprehensive monitoring
✅ Streamlined Codebase: Removed development components for production focus

🌍 Registry Availability

GitHub Container Registry: ghcr.io/sanketskasar/hubspot-mcp-server:latest
Docker Hub: sanketskasar/hubspot-mcp-server:latest
Multi-Platform: Both registries support AMD64 and ARM64 architectures

🔧 Key Capabilities

21 MCP Protocol Endpoints: Complete compliance with MCP Protocol Version 2024-11-05
aiohttp.ClientSession Support: Optimized session management for langchain_mcp_adapters
15+ HubSpot Tools: Full CRUD operations for contacts, companies, and deals
8+ Live Resources: Real-time access to HubSpot CRM data and schemas
5+ Ready-to-Use Prompts: Business intelligence and automation templates
Advanced Monitoring: Health, readiness, metrics, and status endpoints
Enterprise Security: Non-root execution, security headers, rate limiting

🎯 Built with ❤️ for the MCP ecosystem

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables comprehensive HubSpot CRM integration through the Model Context Protocol with 15+ tools for managing contacts, companies, and deals. Supports multiple transport protocols (HTTP, SSE, STDIO) with session management and real-time access to CRM data.

Related MCP Servers

HubSpot MCP Server
peakmojo
A
security
A
license
A
quality
Enables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management.
Last updated -
102
MIT License
HubSpot MCP Server
SheffieldP
-
security
A
license
-
quality
A server that enables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management with multi-user token-based authentication.
Last updated -
MIT License
HubSpot MCP
shinzo-labs
A
security
A
license
A
quality
A Model Context Protocol implementation for the HubSpot API that provides a standardized interface for accessing and managing CRM data, including companies, contacts, deals, and other objects with comprehensive CRUD operations and association management.
Last updated -
14
20
MIT License
HubSpot MCP Server
KaranThink41
-
security
A
license
-
quality
A Model Context Protocol server that provides tools for interacting with HubSpot CRM, allowing users to create, update, delete, and fetch summary records stored as Note engagements in HubSpot.
Last updated -
MIT License

View all related MCP servers