CRI--HubSpot-MCP-Server by tcochrancri - MCP Server

HubSpot MCP Server for OpenAI Agent Builder

This project provides a complete integration between HubSpot's CRM and OpenAI's Agent Builder through the Model Context Protocol (MCP). It includes OAuth authentication, MCP server connection, and direct HubSpot API access.

Features

🔐 OAuth 2.0 Authentication - Secure HubSpot app authentication
🔌 MCP Server Integration - Connect to HubSpot MCP server
📊 CRM Data Access - Direct access to contacts, companies, deals, and tickets
🚀 OpenAI Agent Builder Ready - Pre-configured for Agent Builder integration
📈 Production Grade - Comprehensive error handling and logging

Prerequisites

Before starting, you'll need:

HubSpot Developer Account - Join the HubSpot MCP server (remote) beta
HubSpot CLI - Version 7.6.0 or later (hs --version)
Node.js - Version 16 or later
OpenAI API Key - For Agent Builder integration

Quick Start

1. Clone and Install

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

2. Configure Environment

cp env.example .env

Edit .env with your credentials:

HUBSPOT_CLIENT_ID=your_client_id_here
HUBSPOT_CLIENT_SECRET=your_client_secret_here
HUBSPOT_REDIRECT_URI=http://localhost:3000/oauth-callback
PORT=3000
OPENAI_API_KEY=your_openai_api_key_here

3. Upload HubSpot App

# Upload your app configuration to HubSpot
hs project upload

4. Start the Server

npm start

The server will be available at http://localhost:3000

API Endpoints

OAuth Authentication

GET /oauth/authorize - Start OAuth flow
GET /oauth/callback - Handle OAuth callback
POST /oauth/refresh - Refresh access token
GET /oauth/token/:tokenId - Get token information

MCP Server Integration

POST /mcp/connect - Connect to HubSpot MCP server
GET /mcp/status - Check MCP connection status
GET /mcp/capabilities - Test MCP server capabilities
DELETE /mcp/disconnect - Disconnect from MCP server

HubSpot CRM Data

GET /hubspot/contacts - Get contacts
GET /hubspot/companies - Get companies
GET /hubspot/deals - Get deals
GET /hubspot/tickets - Get tickets
GET /hubspot/summary - Get CRM summary
GET /hubspot/search - Search CRM data

HubSpot App Configuration

The app is configured with the following settings:

{
  "uid": "user-level-app",
  "type": "app",
  "config": {
    "description": "A user level app template that can be used to connect with HubSpot MCP server",
    "name": "user level app",
    "distribution": "marketplace",
    "isUserLevel": true,
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "http://localhost",
        "http://localhost:3000/oauth-callback",
        "https://oauth.myapplication.com/oauth-callback"
      ],
      "requiredScopes": [
        "oauth",
        "crm.objects.contacts.read",
        "crm.objects.companies.read",
        "crm.objects.deals.read",
        "crm.objects.tickets.read"
      ],
      "optionalScopes": [
        "crm.objects.products.read",
        "crm.objects.orders.read",
        "crm.objects.line_items.read",
        "crm.objects.invoices.read",
        "crm.objects.quotes.read",
        "crm.objects.subscriptions.read",
        "crm.objects.users.read",
        "crm.objects.owners.read"
      ]
    }
  }
}

Installation Flow

1. Create HubSpot App

Create a new app on the HubSpot developer platform
Set distribution to "marketplace"
Set auth to "oauth"
Set isUserLevel to true
Upload the app configuration

2. Configure OAuth Scopes

Add the required CRM object scopes:

{
  "requiredScopes": [
    "oauth",
    "crm.objects.contacts.read",
    "crm.objects.companies.read",
    "crm.objects.deals.read",
    "crm.objects.tickets.read"
  ],
  "optionalScopes": [
    "crm.objects.products.read",
    "crm.objects.orders.read",
    "crm.objects.line_items.read"
  ]
}

3. Install the App

Navigate to app distribution settings
Click "Begin publishing"
Sign the Acceptable Use Policy (AUP)
Copy the install URL
Use the install URL to install the app in your HubSpot account

OpenAI Agent Builder Integration

MCP Server Connection

Get Access Token: Use the OAuth flow to obtain an access token
Connect to MCP: Use the access token to connect to https://mcp.hubspot.com
Configure Agent Builder: Use the MCP server URL and access token in your Agent Builder configuration

Example Configuration

{
  "mcp_server_url": "https://mcp.hubspot.com",
  "access_token": "your_access_token_here",
  "capabilities": [
    "contacts.read",
    "companies.read",
    "deals.read",
    "tickets.read"
  ]
}

Development

Running in Development Mode

npm run dev

Testing

npm test

Project Structure

src/
├── config/
│   └── app-config.json    # HubSpot app configuration
├── routes/
│   ├── oauth.js           # OAuth authentication routes
│   ├── mcp.js             # MCP server integration routes
│   └── hubspot.js         # HubSpot CRM data routes
└── index.js               # Main server file

Error Handling

The server includes comprehensive error handling:

OAuth Errors: Invalid state, missing codes, token exchange failures
MCP Errors: Connection failures, capability test failures
API Errors: HubSpot API rate limits, authentication failures
Validation: Missing parameters, invalid tokens

All errors are logged with timestamps and include helpful error messages.

Security Considerations

Token Storage: Tokens are stored in memory (use database in production)
State Validation: OAuth state parameters are validated for security
HTTPS: Use HTTPS in production for secure token transmission
Token Expiration: Access tokens are automatically refreshed when needed

Troubleshooting

Common Issues

OAuth Callback Errors: Ensure redirect URI matches exactly
MCP Connection Failures: Verify access token is valid and has required scopes
API Rate Limits: Implement proper rate limiting for production use
Token Expiration: Set up automatic token refresh

Debug Mode

Enable debug logging by setting:

NODE_ENV=development
DEBUG=hubspot-mcp:*

License

MIT License - see LICENSE file for details.

Support

For support and questions:

Documentation: HubSpot Developer Docs
MCP Server: HubSpot MCP Beta
OpenAI Agent Builder: OpenAI Documentation