@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

npm install @plugix/mcp-hubspot

Or run directly:

npx @plugix/mcp-hubspot

Configuration

Set environment variables:

# 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
2. Create a Private App in Settings > Integrations > Private Apps
3. Grant the required scopes (see below)
4. Copy the access token

Usage

Development

npm run dev

Production

npm run build
npm start

Docker

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

Claude Desktop Integration

Add to claude_desktop_config.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:

{
  "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:

{
  "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:

{
  "name": "create_contact",
  "arguments": {
    "email": "[email protected]",
    "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:

{
  "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:

{
  "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:

{
  "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

npm test

License

MIT