204 lines
5.1 KiB
Markdown
204 lines
5.1 KiB
Markdown
# HubSpot MCP Server
|
|
|
|
Model Context Protocol (MCP) server for HubSpot CRM API v3. Provides comprehensive access to HubSpot CRM objects, marketing tools, CMS, and analytics.
|
|
|
|
## Features
|
|
|
|
- **CRM Objects**: Contacts, Companies, Deals, Tickets, Line Items, Products, Quotes
|
|
- **Associations**: Manage relationships between objects
|
|
- **Marketing**: Email campaigns, forms, lists, workflows
|
|
- **CMS**: Blog posts, pages, HubDB tables
|
|
- **Engagements**: Notes, calls, emails, meetings, tasks
|
|
- **Pipelines & Stages**: Deal and ticket pipeline management
|
|
- **Search API**: Advanced filtering and search across all objects
|
|
- **Batch Operations**: Efficient bulk create/update/archive
|
|
- **Rate Limiting**: Automatic retry with exponential backoff
|
|
- **Pagination**: Automatic handling of cursor-based pagination
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file (see `.env.example`):
|
|
|
|
```bash
|
|
HUBSPOT_ACCESS_TOKEN=your-private-app-token-here
|
|
```
|
|
|
|
### Getting a HubSpot Access Token
|
|
|
|
1. Go to your HubSpot account settings
|
|
2. Navigate to **Integrations** → **Private Apps**
|
|
3. Click **Create a private app**
|
|
4. Configure the required scopes:
|
|
- `crm.objects.contacts.read` / `crm.objects.contacts.write`
|
|
- `crm.objects.companies.read` / `crm.objects.companies.write`
|
|
- `crm.objects.deals.read` / `crm.objects.deals.write`
|
|
- `crm.objects.owners.read`
|
|
- Additional scopes based on your needs
|
|
5. Copy the generated access token
|
|
|
|
## Usage
|
|
|
|
### Development Mode
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### MCP Configuration
|
|
|
|
Add to your MCP client configuration (e.g., Claude Desktop):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"hubspot": {
|
|
"command": "node",
|
|
"args": ["/path/to/hubspot/dist/main.js"],
|
|
"env": {
|
|
"HUBSPOT_ACCESS_TOKEN": "your-token-here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
### Contacts
|
|
|
|
- `hubspot_contacts_list` - List all contacts with pagination
|
|
- `hubspot_contacts_get` - Get a contact by ID
|
|
- `hubspot_contacts_create` - Create a new contact
|
|
- `hubspot_contacts_update` - Update contact properties
|
|
- `hubspot_contacts_search` - Search contacts with filters
|
|
|
|
### Companies
|
|
|
|
- `hubspot_companies_list` - List all companies
|
|
- `hubspot_companies_get` - Get a company by ID
|
|
- `hubspot_companies_create` - Create a new company
|
|
|
|
### Deals
|
|
|
|
- `hubspot_deals_list` - List all deals
|
|
- `hubspot_deals_get` - Get a deal by ID
|
|
- `hubspot_deals_create` - Create a new deal
|
|
|
|
### Tickets
|
|
|
|
- `hubspot_tickets_list` - List all tickets
|
|
- `hubspot_tickets_create` - Create a new ticket
|
|
|
|
### Associations
|
|
|
|
- `hubspot_associations_get` - Get associations for an object
|
|
- `hubspot_associations_create` - Create an association between objects
|
|
|
|
### Pipelines
|
|
|
|
- `hubspot_pipelines_list` - List pipelines for an object type
|
|
|
|
### Owners
|
|
|
|
- `hubspot_owners_list` - List all owners in the account
|
|
|
|
### Properties
|
|
|
|
- `hubspot_properties_list` - List properties for an object type
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **`src/types/index.ts`** - Comprehensive TypeScript type definitions for all HubSpot entities
|
|
2. **`src/clients/hubspot.ts`** - API client with retry logic, rate limiting, and pagination
|
|
3. **`src/server.ts`** - MCP server implementation with lazy-loaded tool modules
|
|
4. **`src/main.ts`** - Entry point with environment validation and graceful shutdown
|
|
|
|
### API Client Features
|
|
|
|
- **Authentication**: Bearer token (Private App or OAuth)
|
|
- **Rate Limiting**: Automatic handling of 429 responses with retry-after headers
|
|
- **Retry Logic**: Exponential backoff for transient failures (max 3 retries)
|
|
- **Pagination**: Automatic cursor-based pagination (HubSpot uses `after` cursor)
|
|
- **Batch Operations**: Efficient bulk operations for create/update/archive
|
|
- **Type Safety**: Full TypeScript type definitions for all API entities
|
|
|
|
### HubSpot API Limits
|
|
|
|
- **Free/Starter**: 10 requests/second
|
|
- **Professional/Enterprise**: Higher limits based on tier
|
|
- **Search API**: Up to 10,000 results per search
|
|
- **Batch API**: Up to 100 objects per batch request
|
|
|
|
## Error Handling
|
|
|
|
The server provides structured error responses:
|
|
|
|
```typescript
|
|
{
|
|
content: [{
|
|
type: 'text',
|
|
text: 'Error: HubSpot API Error: {message} ({status}) [{correlationId}]'
|
|
}],
|
|
isError: true
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
### Type Safety
|
|
|
|
All HubSpot entities use branded types for IDs:
|
|
|
|
```typescript
|
|
type ContactId = string & { readonly __brand: 'ContactId' };
|
|
type CompanyId = string & { readonly __brand: 'CompanyId' };
|
|
```
|
|
|
|
### Adding New Tools
|
|
|
|
1. Add tool definition in `src/server.ts` → `ListToolsRequestSchema` handler
|
|
2. Add routing in `handleToolCall` method
|
|
3. Implement handler method (or lazy-load from separate module)
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
npm test # (tests not yet implemented)
|
|
```
|
|
|
|
### Type Checking
|
|
|
|
```bash
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [HubSpot API Documentation](https://developers.hubspot.com/docs/api/overview)
|
|
- [HubSpot CRM API v3](https://developers.hubspot.com/docs/api/crm/understanding-the-crm)
|
|
- [Model Context Protocol](https://modelcontextprotocol.io)
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
For issues and feature requests, please open an issue on GitHub.
|