PrescriberPoint/hubspot-mcp

HubSpot MCP Server

Beta - Model Context Protocol (MCP) Server for HubSpot CRM

A TypeScript-based MCP server that enables AI assistants to send transactional emails through HubSpot's Single Send API.

Features

• Send Transactional Emails: Send personalized transactional emails via HubSpot
• Dual Transport Support:
  • stdio for local/CLI usage
  • HTTP Streaming Protocol for remote deployments
• Secure by Default: API key authentication for HTTP deployments
• Type-safe: Built with TypeScript for reliability

Prerequisites

• Node.js 18 or higher
• A HubSpot account with API access
• HubSpot Private App or OAuth access token

Installation

npm install
npm run build

Configuration

HubSpot API Setup

1. Create a HubSpot Private App:

   • Navigate to Settings > Integrations > Private Apps in your HubSpot account
   • Create a new private app
   • Grant the following scope: transactional-email
   • Copy the generated access token

2. Set up environment variables:

# Required
HUBSPOT_ACCESS_TOKEN=your_hubspot_access_token

# Optional - for HTTP transport security
MCP_API_KEY=your_secret_api_key

Or create a .env file:

HUBSPOT_ACCESS_TOKEN=pat-na1-xxx-xxx-xxx
MCP_API_KEY=your-secure-random-key

Usage

stdio Transport (Local/CLI)

Use stdio transport for local development or integration with Claude Desktop and other MCP clients.

Claude Desktop Configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/path/to/hubspot-mcp/build/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your_hubspot_access_token"
      }
    }
  }
}

Direct Invocation:

HUBSPOT_ACCESS_TOKEN=your_token node build/index.js

HTTP Transport (Remote Deployment)

For remote deployments, the server supports HTTP with SSE (Server-Sent Events).

Start the HTTP server:

# With API key authentication
MCP_API_KEY=your_secret_key npm start -- --transport http --port 3000

# Or via environment
export MCP_API_KEY=your_secret_key
npm start -- --transport http --port 3000

Client Configuration:

Clients must include the Authorization header:

Authorization: Bearer your_secret_key

Example with curl:

curl -X POST http://localhost:3000/mcp/v1 \
  -H "Authorization: Bearer your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Available Tools

send_email

Sends a transactional email using HubSpot's Single Send API.

Parameters:

Example:

{
  "emailId": "12345678",
  "to": "customer@example.com",
  "customProperties": {
    "order_number": "ORD-12345",
    "order_total": "$99.99",
    "tracking_url": "https://track.example.com/12345"
  }
}

Response:

{
  "success": true,
  "statusId": "SENT",
  "sendResult": "SENT"
}

Examples

Sending an Order Confirmation Email

// Using the MCP client
const result = await mcpClient.callTool("send_email", {
  emailId: "87654321",
  to: "customer@example.com",
  customProperties: {
    customer_name: "John Doe",
    order_number: "ORD-2024-001",
    order_date: "2024-10-07",
    order_total: "$149.99",
    shipping_address: "123 Main St, Anytown, USA"
  }
});

Sending a Password Reset Email

const result = await mcpClient.callTool("send_email", {
  emailId: "11223344",
  to: "user@example.com",
  customProperties: {
    reset_link: "https://app.example.com/reset?token=abc123",
    expiry_time: "1 hour"
  }
});

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Project Structure

hubspot-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── transports/
│   │   ├── stdio.ts          # stdio transport
│   │   └── http.ts           # HTTP/SSE transport
│   ├── tools/
│   │   └── sendEmail.ts      # Send email tool implementation
│   └── utils/
│       └── hubspot.ts        # HubSpot API client
├── package.json
├── tsconfig.json
└── README.md

Security Considerations

HTTP Deployment

⚠️ Important: When deploying over HTTP:

1. Always use HTTPS in production (use a reverse proxy like nginx or Caddy)
2. Set a strong MCP_API_KEY - use a cryptographically random key:

   # Generate a secure API key
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

3. Restrict network access - use firewall rules to limit which clients can connect
4. Monitor usage - implement rate limiting and logging for abuse detection
5. Rotate keys regularly - update your MCP_API_KEY periodically

HubSpot Access Token

• Never commit your HUBSPOT_ACCESS_TOKEN to version control
• Use environment variables or secure secret management
• Limit token scopes to only what's needed (transactional-email)
• Consider using OAuth for user-specific access

API Reference

HubSpot Single Send API

This server uses HubSpot's Transactional Email API:

• API Documentation
• Authentication Guide

MCP Specification

This server implements:

• MCP Core Specification
• stdio Transport
• HTTP Streaming Transport

Troubleshooting

"Unauthorized" Error

• Verify your HUBSPOT_ACCESS_TOKEN is correct
• Ensure your HubSpot Private App has the transactional-email scope
• Check that the token hasn't expired

"Email ID not found"

• Confirm the emailId exists in your HubSpot account
• Navigate to Marketing > Transactional Emails in HubSpot to find valid IDs

HTTP Connection Issues

• Verify MCP_API_KEY is set when using HTTP transport
• Ensure the client is sending the Authorization: Bearer <key> header
• Check firewall rules and network connectivity

Roadmap

Future enhancements may include:

• Additional HubSpot CRM tools (contacts, deals, tickets)
• Support for batch email sending
• Email template management
• Webhook support for delivery status updates
• OAuth flow for user authentication

Contributing

This is a beta project. Contributions, bug reports, and feature requests are welcome!

License

MIT

Support

For issues and questions:

• HubSpot API: HubSpot Developer Documentation
• MCP Protocol: Model Context Protocol Documentation
• This project: GitHub Issues

Note: This is a beta release. APIs and configuration options may change in future versions.