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 hubspot-oauth-app/DEPLOY.md.

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