hubspot-intelligence-mcp

DripEmail/hubspot-intelligence-mcp

3.1

If you are the rightful owner of hubspot-intelligence-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The HubSpot Intelligence MCP Server connects Claude to HubSpot's CRM, enabling natural language queries to transform into comprehensive customer insights by aggregating data from HubSpot CRM.

Tools
6
Resources
0
Prompts
0

HubSpot Intelligence MCP Server

A custom MCP (Model Context Protocol) server that connects Claude to HubSpot's CRM for executive customer intelligence. Transform natural language questions into comprehensive customer insights by aggregating data from HubSpot CRM.

🎯 What This Enables

Transform natural language questions into comprehensive customer intelligence:

Executive Queries → Real Data

  • "Tell me about our relationship with TheFeed" → Complete customer overview with $6,195 in deals, 33 contacts, support history
  • "What's our deal pipeline status?" → Live revenue data and sales stages
  • "Show me support ticket trends" → Customer service metrics and issue patterns
  • "Who are our top accounts by revenue?" → Ranked customer analysis with engagement data

The Magic: One Question = Multiple Systems

  • HubSpot (this server) → CRM data, deals, contacts, support tickets, emails
  • JIRA MCP → Development tickets, feature requests
  • Zendesk MCP → Support interactions, satisfaction scores
  • AI Synthesis → Executive-ready insights combining all sources

🚀 Quick Start

Quick Setup (Automated)

  1. Set up OAuth app (one-time):

    ./setup-oauth.sh

    This deploys your HubSpot OAuth app and extracts credentials automatically.

  2. Complete the setup:

    ./setup-complete.sh

    This will:

    • Install dependencies
    • Get OAuth tokens via browser
    • Build the MCP server
    • Configure Claude Desktop

  3. Restart Claude Desktop and test with: "Find information about our top customers"

For Developers

Same automated setup as above:

  1. Clone the repository:

    git clone https://github.com/yourusername/hubspot-intelligence-mcp.git
cd hubspot-intelligence-mcp

  2. Set up OAuth app (one-time):

    ./setup-oauth.sh

  3. Complete the setup:

    ./setup-complete.sh

  4. Restart Claude Desktop and test

🔧 Customer Intelligence Tools

Core Tools (All Live & Tested)

  1. search_customers - Find companies and contacts by name or keyword
  2. get_customer_overview - Complete customer relationship analysis
  3. get_customer_deals - Sales pipeline and revenue analysis
  4. get_customer_tickets - Support ticket history and trends
  5. get_customer_contacts - Contact directory and org chart
  6. get_top_accounts - Revenue-ranked customer intelligence

Data Coverage

  • Companies: Name, domain, industry, location, employee count, revenue
  • Contacts: Names, emails, phones, job titles, lifecycle stages
  • Deals: Values, stages, close dates, pipelines, descriptions
  • Tickets: Subjects, priorities, categories, resolution status
  • Emails: Communications history, directions, timestamps

🏗️ Technical Architecture

Claude Desktop ←→ MCP Protocol ←→ HubSpot Intelligence Server ←→ OAuth 2.0 ←→ HubSpot APIs
                                           ↓
                               ┌─ Companies API
                               ├─ Contacts API  
                               ├─ Deals API
                               ├─ Tickets API
                               └─ Associations API

Key Components

  1. MCP Protocol Handler - Implements MCP server specification with 6 customer intelligence tools
  2. HubSpot API Client - Manages OAuth 2.0 tokens with auto-refresh and rate limiting
  3. Intelligence Service - Business logic for customer data aggregation and analysis
  4. Data Aggregation - Combines data from multiple HubSpot objects for executive insights

📦 Distribution Options

For Everyone

  • Fully automated setup (./setup-complete.sh)
  • Zero manual configuration required
  • Cross-platform support (macOS, Linux, Windows)

For Developers

  • GitHub repository with comprehensive documentation
  • npm package distribution ready
  • Docker containerization for enterprise deployment

For Enterprise

  • Docker Compose orchestration
  • Internal package registry support
  • Security and compliance considerations

🔐 Security & OAuth Setup

Included OAuth App

This repository includes a complete HubSpot OAuth app in the hubspot-oauth-app/ directory that's pre-configured with all required scopes. No need to create your own app!

Quick Deploy the OAuth App:

cd hubspot-oauth-app
./deploy.sh

For detailed deployment instructions, see .

Required Scopes (Pre-configured)

  • oauth - OAuth authentication
  • crm.objects.companies.read - Company data
  • crm.objects.contacts.read - Contact information
  • crm.objects.deals.read - Sales pipeline data
  • tickets - Support ticket access
  • sales-email-read - Email communications (critical for complete customer intelligence)
  • conversations.read - Chat/conversation history
  • crm.objects.users.read - User information
  • crm.objects.owners.read - Owner/assignee data

OAuth App Features

  • ✅ Marketplace ready - Configured for HubSpot App Marketplace distribution
  • ✅ All scopes included - No "permission denied" errors on customer data
  • ✅ Professional setup - Real support contacts and documentation URLs
  • ✅ One-click deploy - Simple script-based deployment

Token Management

  • Environment-based configuration - No hardcoded credentials in source code
  • Interactive OAuth flow - Secure browser-based token acquisition
  • Automatic token refresh using refresh tokens
  • Secure token storage via environment variables
  • OAuth 2.0 best practices implementation
  • Format validation - Helpful error messages for credential setup

📊 Live Test Results

Verified Working Queries

✅ "search_customers thefeed"
   → Found TheFeed.com (Boulder, CO) + 4 similar companies
   → 33 contacts including Matt Johnson (CTO), Riley (Dev Director)

✅ "get_customer_overview TheFeed.com"  
   → $6,195 in active deals, 33 contacts, 1 deal pipeline
   → Industry: RETAIL, 50 employees, $1M annual revenue
   → Last activity: Sept 10, 2025

✅ All 6 MCP tools responding with real HubSpot data

📋 Files Overview

  • src/ - TypeScript source code for the MCP server
  • hubspot-oauth-app/ - Complete HubSpot OAuth app with deployment scripts
    • app-hsmeta.json - OAuth app configuration with all required scopes
    • hsproject.json - HubSpot project configuration
    • deploy.sh - One-click OAuth app deployment script
    • DEPLOY.md - OAuth app deployment documentation
  • setup-for-ceo.sh - One-click setup script for executives
  • get-tokens.js - Secure OAuth token acquisition script (environment-based)
  • claude-desktop-config.example.json - Claude Desktop configuration template
  • .env.example - Environment variables template
  • DEPLOYMENT.md - Comprehensive deployment guide

🆘 Troubleshooting

Common Issues

  • "Node.js not found" → Install Node.js 18+ from nodejs.org
  • "Invalid access token" → Check tokens in .env are correct and haven't expired
  • "MCP server not connecting" → Restart Claude Desktop and verify file paths

Support

For technical issues, see DEPLOYMENT.md or contact your development team.

🎯 Perfect for AI Jam 2025

Your HubSpot Intelligence MCP server is fully operational and ready for executive customer intelligence demos:

  • ✅ Authenticates with HubSpot via OAuth 2.0
  • ✅ Queries all major CRM objects (companies, contacts, deals, tickets, emails)
  • ✅ Aggregates data into executive-ready insights
  • ✅ Integrates with Claude Desktop for natural language queries
  • ✅ Works alongside other MCP servers for complete customer intelligence

Perfect for demonstrating "One question → Multiple business systems → Executive insights"

Built for AI Jam 2025 - Executive Customer Intelligence Platform