What can you do with this server?

This server lets AI agents interact with HubSpot CRM through four tools for contact, company, and activity management: * Look up a contact (hubspot_get_contact): Retrieve a contact's first name, last name, lifecycle stage, and associated company by email address. * Search companies (hubspot_search_companies): Find companies by name or domain, returning matching company names and domains. * Create or update a contact (hubspot_create_contact): Create a new contact or update an existing one (upsert by email), with optional first name, last name, and company. * Log an activity (hubspot_log_activity): Log a note, email, or call on a specific contact's timeline by providing the contact ID, activity type, and body text.

Which integrations are available for this server?

Provides tools for managing HubSpot CRM data, including retrieving and creating contacts, searching companies, and logging activities (notes, emails, calls) on contact timelines.

How do I use HubSpot MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HubSpot MCP Server find contact by email jane@example.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

HubSpot MCP Server

by djmoore-projects

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Remote

HubSpot MCP Server

License: MIT Node

A Model Context Protocol (MCP) server that exposes HubSpot CRM data and actions as tools for AI agents (Claude, Cursor, and any other MCP-compatible client) — so an agent can look up a contact, search companies, upsert a lead, and log a call or note, all through typed, validated tool calls instead of hand-rolled API glue.

Battle-tested against a live HubSpot account: contact lookup/upsert, company search, and note logging all verified end-to-end (see Tools for sample I/O).

If you find this useful, a star helps other people building MCP integrations find it.

Architecture

src/
  hubspotClient.ts   HubSpot REST API wrapper (auth, requests, 429 retry, typed responses)
  index.ts           MCP server: tool definitions + stdio transport wiring

Transport: StdioServerTransport — the server communicates with its MCP client over stdin/stdout, so it's launched as a subprocess (no network port to manage).
Auth: A HubSpot Private App access token is read from the HUBSPOT_ACCESS_TOKEN environment variable at startup. The token is never hardcoded or logged.
Error handling: All HubSpot API calls go through HubSpotClient, which:
- Converts network/HTTP failures into a typed HubSpotApiError with a client-safe message.
- Retries 429 Too Many Requests responses (respecting the Retry-After header, with exponential backoff as a fallback) up to 2 times before surfacing the error.
- Never throws out of a tool handler — index.ts catches every error and returns an MCP isError: true tool result instead of crashing the server.
Tool schemas: Each tool's input is defined with zod, giving strict runtime validation and auto-generated JSON Schema for the MCP client.

Related MCP server: HubSpot MCP Server

Setup

cd hubspot-mcp-server
npm install
cp .env.example .env   # then fill in HUBSPOT_ACCESS_TOKEN
npm run build

Generate a HubSpot Private App access token: HubSpot → Settings → Integrations → Private Apps → Create a private app. Grant at minimum:

crm.objects.contacts.read / crm.objects.contacts.write
crm.objects.companies.read
crm.objects.notes.write (or the relevant engagements scope for the activity types you plan to log)

Running standalone

HUBSPOT_ACCESS_TOKEN=pat-xxxxx npm start

For local development without a build step:

HUBSPOT_ACCESS_TOKEN=pat-xxxxx npm run dev

Configuring Claude Desktop

Add this server to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/absolute/path/to/hubspot-mcp-server/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-xxxxx"
      }
    }
  }
}

Restart Claude Desktop after saving. The four HubSpot tools will appear in the tool picker.

Tools

`hubspot_get_contact`

Look up a contact by email.

{ "email": "jane.doe@example.com" }

Returns first name, last name, lifecycle stage, and associated company name (if any).

`hubspot_search_companies`

Search companies by name or domain.

{ "query": "acme" }

Returns matching company names and domains.

`hubspot_create_contact`

Create a contact, or update it if the email already exists.

{
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "company": "Acme Corp"
}

`hubspot_log_activity`

Log an engagement on a contact's timeline.

{
  "contactId": "12345",
  "activityType": "NOTE",
  "body": "Discussed renewal timeline on the call."
}

activityType is one of NOTE, EMAIL, or CALL.

Notes

Rate limits: HubSpot returns 429 when the account's rate limit is exceeded. The client retries automatically; if retries are exhausted, the tool returns a clear error message rather than crashing.
All tool errors (invalid input, HubSpot API errors, network failures) are returned as MCP tool errors (isError: true) so the calling agent can react instead of the server process dying.

License

MIT — see LICENSE.

Available Tools

4 tools

hubspot_create_contactA

Create a new HubSpot contact, or update an existing one if the email already exists.

ParametersJSON Schema

Name	Required	Description
`email`	Yes	The contact's email address (used as the unique key).
`company`	No	The contact's company name.
`lastName`	No	The contact's last name.
`firstName`	No	The contact's first name.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description correctly discloses the upsert behavior but omits other behavioral traits like rate limits, required permissions, or return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence clearly states the core functionality with no unnecessary words. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimal and does not mention return behavior or provide guidance on sibling tools. For a simple tool this is acceptable but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all parameters (100%), so the description adds no new meaning beyond reiterating the email as unique key. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates or updates a HubSpot contact based on email. It distinguishes from siblings like hubspot_get_contact (read) and hubspot_search_companies (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for create/update by email but lacks explicit guidance on when to use this vs alternatives like hubspot_get_contact for reading.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hubspot_get_contactA

Look up a HubSpot contact by email address. Returns first name, last name, lifecycle stage, and associated company name.

ParametersJSON Schema

Name	Required	Description	Default
`email`	Yes	The contact's email address to search for.

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description should fully disclose behavior. It only lists returned fields, omitting error handling, idempotency, or side effects. Missing transparency on what happens if email is not found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the core action and return fields, with no redundant or extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers purpose and return fields but lacks output schema and details on error behavior or edge cases. Adequate for a simple lookup but incomplete for robust agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and describes the email parameter. The description's phrase 'by email address' is redundant. No additional semantics beyond schema are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Look up' and resource 'HubSpot contact by email address', clearly distinguishing from sibling tools like hubspot_create_contact (create) and hubspot_search_companies (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when/when-not-to-use guidance is provided. The context implies usage when needing contact details by email, but does not mention alternatives or exclusions like creating contacts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hubspot_log_activityB

Log an engagement (note, email, or call) on a contact's HubSpot timeline.

ParametersJSON Schema

Name	Required	Description
`body`	Yes	The text content/body of the activity.
`contactId`	Yes	The HubSpot contact ID to log the activity against.
`activityType`	Yes	The type of engagement to log.

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It states 'Log' which implies a write operation, but does not disclose any side effects, permissions required, or limitations. The description is minimal and adds little beyond the parameter schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 12 words, efficiently stating the purpose. It is front-loaded and contains no unnecessary information. Could be improved by adding brief usage context, but it is appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters all described and no output schema, the description is minimal. It does not explain what the tool returns, error conditions, or caveats. While sufficient for basic understanding, it lacks completeness for complex use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains each parameter. The description adds no extra meaning beyond listing activity types. Baseline score of 3 is appropriate as the description does not harm but adds negligible value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool logs an engagement (note, email, or call) on a contact's HubSpot timeline. It uses a specific verb 'Log' and identifies the resource. However, it does not differentiate from sibling tools, but siblings are distinct in function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The context implies it should be used to log activities on contacts, but lacks exclusions or conditions. Sibling tools are different enough that confusion is unlikely, but guidance would improve usability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hubspot_search_companiesA

Search HubSpot companies by name or domain. Returns matching company names and domains.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Free-text search query, e.g. a company name or domain.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes a straightforward search operation without side effects. However, it does not disclose behavior like pagination, exact match vs fuzzy search, or authentication requirements. Adequate for simple use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence that front-loads the purpose and outcome. No redundant information. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, description covers what it searches and returns. Minor gap: does not mention if results are limited or paginated, but overall sufficiently complete for intended use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'query' parameter, so baseline is 3. Description adds minimal value beyond schema by stating search by name or domain, but essentially restates the schema description. No additional format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool searches HubSpot companies by name or domain and returns matching names/domains. 'Search' is a specific verb, resource is 'HubSpot companies', and output is described. Distinguished from sibling tools which deal with contacts and activities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. However, the sibling tools are for different resources (contacts, activities), so usage context is implied but not stated. Lacks indication of limitations or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv1.0.0Jul 10, 2026
- First observedhubspot_create_contact
- First observedhubspot_get_contact
- First observedhubspot_log_activity
- First observedhubspot_search_companies

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored 2026-07-10 16:45 across 4 tools

Disambiguation5/5

Each tool targets a distinct operation: creating/updating a contact, looking up a contact by email, logging an activity on a contact, and searching companies. No ambiguity between tool purposes.

Naming Consistency5/5

All tools follow a consistent 'hubspot_verb_noun' pattern (e.g., hubspot_create_contact, hubspot_get_contact). The naming is uniform and predictable.

Tool Count5/5

With 4 tools covering core CRM operations (contact CRUD via upsert, activity logging, company search), the count is well-scoped for a focused integration.

Completeness4/5

The set covers essential contact operations (create/upsert, retrieve) and adds activity logging and company search. Missing explicit update or delete tools, but upsert mitigates the gap. Minor missing features like company detail retrieval prevent a perfect score.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

HubSpotOAuth
com.hubspot.app
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Customer Data Platforms Databases Marketing
3
Fiber AI A
ai.fiber
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
Search Customer Data Platforms Marketing
52
FirstTouchOAuth
io.github.First-Touch-Inc
Give AI agents real hands on LinkedIn: sourcing, AI qualification, HubSpot-native attribution.
Social Media AI & Machine Learning CRM
2
PlixanaOAuth
com.plixana
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
CRM Communication
2

Related MCP Servers

HubSpot MCP Server
Databases Search RAG Systems
baryhuang
A
license
B
quality
F
maintenance
Enables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management.
Updated 10 months ago (2025-11-11 18:22 UTC)
16
128
MIT
HubSpot MCP Server
Customer Data Platforms Marketing
ajaystream
A
license
A
quality
D
maintenance
Enables AI clients to seamlessly take HubSpot actions and interact with HubSpot data, allowing users to create/update CRM records, manage associations, and gain insights through natural language.
Updated a year ago (2025-07-24 13:18 UTC)
22
20
MIT
HubSpot MCP Server
Customer Data Platforms Communication Marketing
Manhar-Chaurasia
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with HubSpot CRM for managing contacts, companies, deals, and sending emails through natural language commands.
Updated 10 months ago (2025-11-17 07:31 UTC)
275
MIT
BackCrew HubSpot MCP Server
CRM Search
jayson-svg
A
license
B
quality
B
maintenance
Enables AI assistants to interact with a HubSpot CRM account via natural language, starting with read-only lookups and optionally enabling write operations like creating contacts, deals, and notes.
Updated 2 months ago (2026-07-22 15:32 UTC)
11
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/djmoore-projects/hubspot-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server