HubSpot

HubSpot MCP Server is a comprehensive Model Context Protocol (MCP) server designed to integrate HubSpot CRM into MCP workflows. It implements all 21 MCP endpoints, supports multiple transport modes (HTTP JSON-RPC, streamable HTTP via SSE, and STDIO for process-based communication), and provides session management, health checks, and structured logging to enable robust, production-ready interactions with HubSpot data. The server exposes tools for HubSpot resources (contacts, companies, deals, etc.), supports create/read/update/delete (CRUD) operations, and handles session persistence and rate limiting to ensure reliable, scalable usage in client applications.

To use the server, connect via the supported transports and issue MCP protocol requests using the initialize call to start a session, followed by tool/resource prompts to list, fetch, create, or modify HubSpot entities. For example, you can initialize a session, query tools like contacts or companies, and perform CRUD operations through the MCP endpoints. If you prefer streaming updates, use the streamable-http transport and subscribe to the MCP /mcp/stream endpoint. For process-based automation or local orchestration, STDIO transport enables direct JSON-RPC communication with the running server process. Ensure you provide your HubSpot private app access token via the HUBSPOT_PRIVATE_APP_ACCESS_TOKEN environment variable for authentication and authorization.

Prerequisites:

• Node.js (v18+ recommended) and npm installed on your machine
• Git to clone the repository (if you are building from source)
• Access to a HubSpot Private App with necessary scopes

Option A: Run directly from source (Node.js)

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Create a .env or environment variables with required config:

HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_hubspot_token_here
TRANSPORT=http
PORT=3000

4. Start the server (adjust path to your server entry if different):

node path/to/server.js

Option B: Run via Docker (recommended if available)

1. Ensure Docker is installed and running.
2. Pull and run the image (example):

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

3. Verify the server is reachable on port 3000 and health checks as described in the README.

Option C: Build with custom port (Docker example)

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

Notes:

• Adjust TRANSPORT and PORT as needed for your environment.
• If you clone and run from source, ensure nodemon or a similar watcher is used in development for auto-restarts.

Tips and common considerations:

• Always supply HUBSPOT_PRIVATE_APP_ACCESS_TOKEN to authenticate requests to HubSpot.
• The server supports multiple transports; pick HTTP for simple RPC calls, streamable-http for real-time updates via SSE, or stdio for programmatic orchestration in scripts.
• Configure rate limits and session timeouts to match your application's load; these settings help prevent abuse and ensure fair usage across clients.
• Use the health endpoint to monitor readiness: curl http://localhost:3000/health
• If you encounter CORS or security-related issues in web apps, adjust the CORS_ORIGIN setting accordingly.
• For production, enable graceful shutdown and proper logging levels to diagnose issues quickly.