Skip to main content
Glama

HubSpot MCP Server

by SanketSKasar
GitHub
JavaScript
MIT License
3
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

HubSpot MCP Server

GitHub Container Registry Docker Hub Docker Pulls License: MIT Node.js Docker MCP Protocol

šŸš€ 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

  1. Go to HubSpot Settings ā†’ Integrations ā†’ Private Apps

  2. Click "Create a private app"

  3. 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

  1. Go to Auth tab

  2. Copy the Access Token (starts with pat-...)

  3. āš ļø 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

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Make your changes and add tests

  4. Ensure all tests pass: npm test

  5. Submit a pull request

šŸ“œ License

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

šŸ”— Related Resources

šŸ“‹ 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

GitHub stars GitHub issues

This server cannot be installed

-
security - not tested
A
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.

  1. āœØ Features
    1. šŸ“¦ Available Images
      1. šŸš€ Quick Start
        1. Prerequisites
        2. 1. Run Container
        3. 2. Verify Installation
      2. šŸ”§ Transport Protocols
        1. HTTP Transport (Default)
        2. Streamable HTTP Transport
        3. STDIO Transport
      3. āš™ļø Configuration
        1. Environment Variables
        2. Docker Compose
      4. šŸ”§ Session Management
        1. Session Creation
        2. Session Persistence Examples
        3. Session Features
      5. šŸ”‘ HubSpot Setup
        1. Step 1: Create Private App
        2. Step 2: Generate Token
        3. Step 3: Test Token
      6. šŸ› ļø Available Tools
        1. Contact Management
        2. Company Management
        3. Deal Management
        4. Relationship & Activity Tools
      7. šŸ“Š Resources
        1. šŸ’” Prompts
          1. šŸ“ˆ Monitoring & Health
            1. Health Endpoints
            2. Example Usage
          2. šŸ”’ Security Features
            1. šŸ› ļø Development
              1. Local Development
              2. Command Line Options
            2. šŸ“Š Performance
              1. Resource Requirements
              2. Monitoring
            3. šŸš€ Building Multi-Architecture Images
              1. šŸ¤ Contributing
                1. Quick Start
              2. šŸ“œ License
                1. šŸ”— Related Resources
                  1. šŸ“‹ Latest Updates - Version 1.0.0
                    1. šŸŽ‰ Production Release Features
                    2. šŸŒ Registry Availability
                    3. šŸ”§ Key Capabilities

                  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 -
                    104
                    MIT License
                    • Linux

                  • 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
                    • Linux

                  • 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 -
                    48
                    22
                    MIT License

                  • HubSpot MCP Server

                    -
                    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.

                  View all related MCP servers

                  Appeared in Searches

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/SanketSKasar/HubSpot-MCP-Server'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server