# 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.