# HubSpot MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![HubSpot API](https://img.shields.io/badge/HubSpot%20API-v3-orange.svg)](https://developers.hubspot.com/docs/api/overview)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.8.0-green.svg)](https://github.com/modelcontextprotocol/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A HubSpot Model Context Protocol server for giving AI agents structured, on-demand access to HubSpot CRM and operating data.

This package is built on top of the original open-source work at [lkm1developer/hubspot-mcp-server](https://github.com/lkm1developer/hubspot-mcp-server.git). The Boondock Labs version expands that foundation with broader HubSpot coverage, MCP API-key authentication support, token-health utilities, incremental fetch controls, and additional tools across HubSpot's CRM, Sales, Marketing, Service, CMS, Commerce, and Operations surfaces.

## What This Server Does

The server exposes HubSpot as a set of typed MCP tools. Instead of loading an entire portal into an agent prompt, the agent can ask for the exact slice of context it needs:

- Recent or updated contacts, companies, deals, tickets, and orders
- Exact CRM records by ID
- Company activity and engagement timelines
- Tasks, notes, and engagement activity
- Pipelines, properties, users, lists, workflows, domains, and associations
- Marketing forms, form submissions, marketing emails, email events, and campaigns
- CMS content such as blog posts, landing pages, site pages, files, and HubDB tables
- Service content such as conversations and knowledge base articles
- Commerce objects such as products, quotes, orders, and line items
- Custom objects and general object search
- HubSpot OAuth token validation, token health, and refresh helpers

The result is a retrieval-first HubSpot interface for agents: discover the right tool, pull the relevant records, then continue reasoning with only the context that matters.

## Why This Version Exists

The original project proved the basic idea: expose HubSpot CRM through MCP. This version has been extended for heavier agent workflows where HubSpot is not just a contact database, but an operating environment.

Important additions include:

- Much wider HubSpot object coverage beyond contacts and companies
- Limit-based retrieval on most list tools
- Incremental `updatedAfter` support on heavy CRM reads
- Cursor-based pagination helpers for HubSpot search and list APIs
- Rate limiting and 429 retry handling
- Token refresh and token health tools
- Support for direct HubSpot tokens or Morphed MCP API-key based auth
- Optional-scope handling for HubSpot features that may not be available in every portal
- More complete property sets for CRM records so agents can reason from richer context

## Installation

```bash
npm install hubspot-mcp-server
```

For local development:

```bash
git clone https://github.com/lkm1developer/hubspot-mcp-server.git
cd hubspot-mcp-server
npm install
npm run build
```

If you are working from this expanded Boondock Labs package, use the package source you received or cloned, then run:

```bash
npm install
npm run build
```

## Authentication

The server supports two authentication modes.

### Direct HubSpot Token

Set one of the supported token environment variables:

```bash
HUBSPOT_ACCESS_TOKEN=your-hubspot-access-token
```

You can also pass the token at startup:

```bash
npm start -- --access-token=your-hubspot-access-token
```

The server also checks:

```bash
HUBSPOT_DEVELOPER_API_KEY=your-token
HUBSPOT_PERSONAL_ACCESS_KEY=your-token
```

### Morphed MCP API Key

For Morphed-managed installs, the server can validate a Morphed MCP API key and retrieve the matching HubSpot OAuth token for that portal.

```bash
MORPHED_MCP_API_KEY=your-mcp-api-key
MORPHED_API_URL=https://morphed.io
```

Or pass the API key at startup:

```bash
npm start -- --api-key=your-mcp-api-key
```

## Running The Server

Build first:

```bash
npm run build
```

Start over stdio:

```bash
npm start
```

Or:

```bash
node dist/index.js
```

The package also includes a `stdio` script:

```bash
npm run stdio
```

## SSE Proxy Mode

For remote or browser-based MCP clients, you can run the server behind `mcp-proxy-auth`:

```bash
npx mcp-proxy-auth node dist/index.js
```

Set the auth verification endpoint:

```bash
AUTH_SERVER_URL=https://your-auth-server.com/verify
```

The SSE endpoint is then available through the proxy, with API-key verification handled before requests reach the MCP server.

## Tool Groups

### Core CRM

- `hubspot_create_contact`
- `hubspot_create_company`
- `hubspot_create_note`
- `hubspot_get_active_companies`
- `hubspot_get_active_contacts`
- `hubspot_get_deals`
- `hubspot_get_tickets`
- `hubspot_get_orders`
- `hubspot_get_current_user`
- `hubspot_update_contact`
- `hubspot_update_company`
- `hubspot_get_contact_by_id`
- `hubspot_get_company_by_id`
- `hubspot_get_deal_by_id`
- `hubspot_get_ticket_by_id`

### Engagements And Activity

- `hubspot_get_company_activity`
- `hubspot_get_recent_engagements`
- `hubspot_search_tasks`
- `hubspot_search_notes`
- `hubspot_get_engagement_associations`
- `hubspot_get_engagement_by_id`

### Sales Hub

- `hubspot_get_pipelines`
- `hubspot_get_properties`
- `hubspot_get_quotes`
- `hubspot_get_users`
- `hubspot_get_lists`
- `hubspot_get_workflows`

### Marketing Hub

- `hubspot_get_forms`
- `hubspot_get_form_submissions`
- `hubspot_get_marketing_emails`
- `hubspot_get_email_events`
- `hubspot_get_campaigns`
- `hubspot_get_analytics`

### Service Hub

- `hubspot_get_conversations`
- `hubspot_get_knowledge_base`

### CMS Hub

- `hubspot_get_blog_posts`
- `hubspot_get_landing_pages`
- `hubspot_get_site_pages`
- `hubspot_get_files`
- `hubspot_get_hubdb_tables`
- `hubspot_get_domains`

### Commerce Hub

- `hubspot_get_products`
- `hubspot_get_line_items`
- `hubspot_get_orders`
- `hubspot_get_quotes`

### Operations And Enterprise

- `hubspot_get_custom_objects`
- `hubspot_search_objects`
- `hubspot_get_associations`

### Token Utilities

- `hubspot_refresh_token`
- `hubspot_validate_token`
- `hubspot_token_health`

## Context Strategy

The server is intentionally tool-first rather than prompt-dump-first.

Agents should not need to load every HubSpot record before doing useful work. They can start from the MCP tool list, choose the object family that matches the task, and request a bounded result set with `limit`, `updatedAfter`, or a specific record ID.

The heavier CRM reads use HubSpot sorting, cursor pagination, date filtering, and explicit property lists so the agent receives useful operational context without pulling the whole portal into memory at once.

That pattern makes the server useful for:

- CRM lookup and account research
- Workflow and list inspection
- Support and knowledge-base review
- Marketing and CMS context gathering
- Commerce object inspection
- Agentic HubSpot operations where the assistant needs just-in-time portal context

## Extending The Server

To add a new HubSpot capability:

1. Add a method to `HubSpotClient` in `src/hubspot-client.ts`.
2. Register the MCP tool schema in `setupToolHandlers` inside `src/index.ts`.
3. Add the `CallToolRequestSchema` handler case in `src/index.ts`.
4. Rebuild with:

```bash
npm run build
```

## Attribution

This package began from [lkm1developer/hubspot-mcp-server](https://github.com/lkm1developer/hubspot-mcp-server.git). The current Boondock Labs package keeps that foundation and expands it into a broader HubSpot MCP surface for richer AI-agent workflows.

HubSpot is a trademark of HubSpot, Inc. This package is not an official HubSpot product.

## License

MIT. See [LICENSE](./LICENSE).