npm package: @plugix/mcp-hubspot
Description: MCP Server for HubSpot - CRM, Marketing, Sales automation
Author: Plugix
Latest version: 0.1.0

# @plugix/mcp-hubspot

MCP server for HubSpot CRM - contacts, companies, deals, tickets, and pipelines.

## Features

- **get_contacts** - List contacts with pagination
- **search_contacts** - Search contacts by email, name, or company
- **create_contact** - Create a new contact (with confirmation)
- **get_companies** - List companies with pagination
- **get_deals** - List deals with stage/pipeline filters
- **update_deal** - Update deal properties (with confirmation)
- **get_tickets** - List support tickets
- **get_pipelines** - Get deal or ticket pipelines with stages

## Installation

```bash
npm install @plugix/mcp-hubspot
```

Or run directly:

```bash
npx @plugix/mcp-hubspot
```

## Configuration

Set environment variables:

```env
# Plugix API connection
API_URL=wss://api.plugix.ai
API_TOKEN=plx_live_your_token_here

# HubSpot credentials
HUBSPOT_ACCESS_TOKEN=pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

### Getting a HubSpot Access Token

1. Go to your [HubSpot Developer Account](https://developers.hubspot.com/)
2. Create a Private App in Settings > Integrations > Private Apps
3. Grant the required scopes (see below)
4. Copy the access token

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Docker

```bash
docker build -t plugix-mcp-hubspot .
docker run --env-file .env plugix-mcp-hubspot
```

### Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@plugix/mcp-hubspot"],
      "env": {
        "API_URL": "wss://api.plugix.ai",
        "API_TOKEN": "plx_live_your_token",
        "HUBSPOT_ACCESS_TOKEN": "pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}
```

## Tools Reference

### get_contacts

Get a list of contacts from HubSpot CRM.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| limit | number | Max contacts to return (default: 100) |
| after | string | Pagination cursor for next page |

**Example:**

```json
{
  "name": "get_contacts",
  "arguments": {
    "limit": 50
  }
}
```

### search_contacts

Search for contacts by various criteria.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| query | string | Free-text search across all fields |
| email | string | Filter by email (partial match) |
| firstName | string | Filter by first name (partial match) |
| lastName | string | Filter by last name (partial match) |
| company | string | Filter by company (partial match) |
| limit | number | Max results (default: 100) |

**Example:**

```json
{
  "name": "search_contacts",
  "arguments": {
    "company": "Acme",
    "limit": 25
  }
}
```

### create_contact

Create a new contact. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| email | string | Yes | Contact email |
| firstName | string | No | First name |
| lastName | string | No | Last name |
| phone | string | No | Phone number |
| company | string | No | Company name |
| lifecycleStage | string | No | subscriber, lead, customer, etc. |
| confirmed | boolean | Yes | Must be `true` to create |

**Example:**

```json
{
  "name": "create_contact",
  "arguments": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Inc",
    "confirmed": true
  }
}
```

### get_companies

Get a list of companies.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| limit | number | Max companies to return (default: 100) |
| after | string | Pagination cursor for next page |

### get_deals

Get deals with optional filters.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| limit | number | Max deals to return (default: 100) |
| after | string | Pagination cursor for next page |
| stage | string | Filter by deal stage ID |
| pipeline | string | Filter by pipeline ID |

**Example:**

```json
{
  "name": "get_deals",
  "arguments": {
    "pipeline": "default",
    "limit": 50
  }
}
```

### update_deal

Update a deal's properties. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| dealId | string | Yes | Deal ID to update |
| name | string | No | New deal name |
| amount | number | No | Deal amount |
| stage | string | No | Deal stage ID |
| closeDate | string | No | Close date (YYYY-MM-DD) |
| confirmed | boolean | Yes | Must be `true` to update |

**Example:**

```json
{
  "name": "update_deal",
  "arguments": {
    "dealId": "12345",
    "amount": 50000,
    "stage": "closedwon",
    "confirmed": true
  }
}
```

### get_tickets

Get support tickets with optional filters.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| limit | number | Max tickets to return (default: 100) |
| after | string | Pagination cursor for next page |
| status | string | Filter by ticket status/stage ID |
| pipeline | string | Filter by pipeline ID |

### get_pipelines

Get pipelines and their stages for deals or tickets.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| objectType | string | Yes | `deals` or `tickets` |

**Example:**

```json
{
  "name": "get_pipelines",
  "arguments": {
    "objectType": "deals"
  }
}
```

## Required HubSpot Scopes

Minimum required scopes for your Private App:

### CRM - Read
- `crm.objects.contacts.read`
- `crm.objects.companies.read`
- `crm.objects.deals.read`
- `crm.objects.tickets.read` (optional)

### CRM - Write
- `crm.objects.contacts.write`
- `crm.objects.deals.write`

### Settings
- `crm.schemas.deals.read` (for pipelines)
- `crm.schemas.tickets.read` (for ticket pipelines)

For read-only access, only include the read scopes.

## Testing

```bash
npm test
```

## License

MIT