HubSpot RevOps Server

A read-only Model Context Protocol server that connects to your HubSpot account via a Private App and gives an AI assistant (Claude) diagnostic and advisory capabilities over your CRM.

What it does

• Audits contacts, companies, deals, pipelines, and workflows for data quality issues
• Diagnoses RevOps maturity across 4 levels
• Identifies at-risk deals, lifecycle funnel bottlenecks, and critical workflow gaps
• Benchmarks your key sales metrics against industry standards
• Guides you step-by-step on how to fix issues manually in HubSpot

Read-only by design. The MCP server never writes to HubSpot. All changes are made by you in the HubSpot UI.

---

Setup

1. Create a HubSpot Private App

1. In HubSpot: Settings → Integrations → Private Apps → Create a private app
2. Give it a name (e.g., "RevOps MCP")
3. Under Scopes, enable:
   • crm.objects.contacts.read
   • crm.objects.companies.read
   • crm.objects.deals.read
   • crm.schemas.contacts.read
   • crm.schemas.companies.read
   • crm.schemas.deals.read
   • crm.objects.owners.read
   • automation (requires Sales Hub Professional)
4. Create the app and copy the Access Token (starts with pat-na1-…)

2. Clone and install

git clone <your-repo-url>
cd server
npm install

3. Configure environment

cp .env.example .env.local
# Edit .env.local and paste your HubSpot Access Token

4. Run locally

npm run dev
# MCP endpoint: http://localhost:3000/api/mcp

---

Deploy to Vercel

Option A — Vercel CLI

npm install -g vercel
vercel
# Follow prompts; add HUBSPOT_ACCESS_TOKEN as an environment variable when asked

Option B — Vercel Dashboard

1. Push this repo to GitHub
2. Import the repo at vercel.com
3. Set root directory to server/
4. Add environment variable: HUBSPOT_ACCESS_TOKEN = pat-na1-…
5. Deploy

The vercel.json already sets maxDuration: 60 for the MCP route.

---

Connect to Claude

Once deployed, add the MCP server to Claude Desktop or Claude.ai:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "hubspot": {
      "url": "https://your-deployment.vercel.app/api/mcp"
    }
  }
}

Claude.ai: Settings → Integrations → Add MCP Server → paste your Vercel URL + /api/mcp

---

Available Tools (15)

Tool	What it does
get_account_overview	Object counts, pipelines, users
audit_properties	Custom + default properties; flags missing critical fields
audit_pipelines	Pipeline stages, probabilities, issues
get_pipeline_health	Open deals with data quality flags
get_at_risk_deals	Deals past close date or with no recent activity
get_lifecycle_distribution	Contact funnel counts + conversion rates
audit_workflows	All active workflows + stale detection
check_critical_workflows	Gap analysis against 12 must-have workflows
get_deal_metrics	Win rate, avg deal size, avg cycle, velocity
get_owner_performance	Open + closed pipeline per sales rep
diagnose_revops_maturity	Level 1–4 maturity score + action plan
get_how_to_guide	Step-by-step how-to for any HubSpot task
search_contacts	Find contacts by name, email, or company
get_owners	List all HubSpot users
get_common_pitfalls	Most frequent HubSpot/RevOps mistakes + fixes

---

Project structure

server/
├── app/
│   ├── api/
│   │   └── mcp/
│   │       └── route.ts      # MCP JSON-RPC 2.0 endpoint
│   └── layout.tsx
├── lib/
│   ├── hubspot.ts            # HubSpot API wrapper (read-only)
│   ├── knowledge.ts          # Embedded RevOps knowledge base
│   └── tools.ts              # Tool definitions + handlers
├── .env.example
├── next.config.ts
├── package.json
├── tsconfig.json
└── vercel.json