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_TIMEOUTseconds - 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 databasehubspot://companies- Live companies databasehubspot://deals- Live deals pipelinehubspot://properties/contacts- Contact property schemahubspot://properties/companies- Company property schemahubspot://properties/deals- Deal property schemahubspot://pipelines/deals- Deal pipeline configurationhubspot://owners- Sales rep/owner information
💡 Prompts
5+ Ready-to-Use Prompts:
analyze_pipeline- Deal pipeline analysis and optimizationcontact_research- Deep contact and company researchlead_scoring- Lead qualification and scoringemail_templates- HubSpot email template generationmeeting_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.
🔗 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
