HubSpot-MCP-Server by SanketSKasar - MCP Server

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 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 file for details.

🔗 Related Resources

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