HubSpot MCP Server

# HubSpot MCP Server [](https://github.com/SanketSKasar/HubSpot-MCP-Server/pkgs/container/hubspot-mcp-server) [](https://hub.docker.com/r/sanketskasar/hubspot-mcp-server) [](https://hub.docker.com/r/sanketskasar/hubspot-mcp-server) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://docker.com/) [](https://modelcontextprotocol.io/) 🚀 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](#hubspot-setup)) ### 1. Run Container **GitHub Container Registry (Recommended):** ```bash 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:** ```bash 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:** ```bash # 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 ```bash # 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: ```bash 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: ```bash 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: ```bash 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 ```bash # 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:** ```yaml 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:** ```bash # 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):** ```bash # 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):** ```bash # 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):** ```bash # 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 ```bash 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 ```bash # 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 ```bash 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 ```bash 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 ```bash # 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 ```bash # 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](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](LICENSE) file for details. ## 🔗 Related Resources - **[Model Context Protocol](https://modelcontextprotocol.io/)** - Official MCP specification - **[HubSpot API Documentation](https://developers.hubspot.com/docs/api/overview)** - HubSpot CRM API - **[MCP Protocol Specification](https://spec.modelcontextprotocol.io/)** - Technical MCP details --- <div align="center"> ## 📋 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 --- <div align="center"> **🎯 Built with ❤️ for the MCP ecosystem** [](https://github.com/SanketSKasar/HubSpot-MCP-Server/stargazers) [](https://github.com/SanketSKasar/HubSpot-MCP-Server/issues) </div>