What Is HubSpot MCP Server?

HubSpot MCP Server connects Claude to your HubSpot CRM, enabling natural language queries against contacts, deals, companies, and campaigns. It is maintained by HubSpot and published under the official @hubspot npm scope.

Quick Facts

Field	Value
Package	`@hubspot/mcp-server`
Install	`npx @hubspot/mcp-server`
Compatible with	Claude Desktop, Claude Code
Status	Active
GitHub	https://github.com/HubSpot/hubspot-mcp-server

What You Can Do With It

CRM queries: Ask Claude to retrieve contact records, filter by properties, or look up company associations directly from HubSpot.
Deal tracking: Pull deal pipeline status, stage history, or deal values without opening the HubSpot UI.
Contact management: Search, summarize, or cross-reference contact data across your CRM.
Marketing analytics: Query campaign performance metrics and engagement data stored in HubSpot.

How to Set It Up

Prerequisites: You need a HubSpot account and a valid API key or private app access token with appropriate CRM scopes.

Step 1 — Verify Node.js is installed

node --version  # v18+ recommended
**Step 2 — Test the server manually**

```bash
npx @hubspot/mcp-server

Step 3 — Configure Claude Desktop

Add the following to your claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-private-app-token-here"
      }
    }
  }
}

Step 4 — Configure Claude Code

For Claude Code, add to your project’s .claude/mcp.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-private-app-token-here"
      }
    }
  }
}

Restart Claude Desktop or reload Claude Code after saving the config.

Works Best With

This server is documented as compatible with Claude Desktop and Claude Code. Both clients support the full MCP tool-calling protocol that this server relies on. Claude Desktop is well-suited for ad hoc CRM lookups during day-to-day work; Claude Code is appropriate when you need CRM data accessible alongside code or scripts in a development workflow.

Known Limitations

Authentication required: The server requires a HubSpot private app access token. Legacy API keys are deprecated by HubSpot; confirm your token type before configuring.
Scope dependencies: The CRM scopes granted to your private app determine what data is accessible. Missing scopes (e.g., crm.objects.deals.read) will result in permission errors at query time, not at startup.
Read vs. write behavior: Verify the current GitHub documentation for which operations are read-only. Assuming write access without confirming can lead to unexpected behavior.
HubSpot API rate limits apply: HubSpot enforces per-second and daily request limits at the account tier level. High-frequency queries through Claude may hit these limits.
npx cold starts: Running via npx fetches the package on first use. Pin a specific version in production environments to avoid unintended updates.