@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
`

$3

1. Go to your HubSpot Developer Account
2. Create a Private App in Settings > Integrations > Private Apps
3. Grant the required scopes (see below)
4. Copy the access token

Usage

$3

`bash
npm run dev
`

$3

`bash
npm run build
npm start
`

$3

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

$3

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

$3

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
}
}
`

$3

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
}
}
`

$3

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
}
}
`

$3

Get a list of companies.

Parameters:

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

$3

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
}
}
`

$3

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
}
}
`

$3

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 |

$3

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:

$3


- crm.objects.contacts.read
- crm.objects.companies.read
- crm.objects.deals.read
- crm.objects.tickets.read (optional)

$3

- crm.objects.contacts.write
- crm.objects.deals.write

$3

- 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