HubSpot — Claude Code MCP server: CRM work from the chat
A local MCP server that exposes HubSpot CRM to your coding agent: contacts, deals, tickets, tasks and files. Handy when you juggle more than one HubSpot account.
claude mcp add --env HUBSPOT_CONFIG_DIR=<HUBSPOT_CONFIG_DIR> --env HUBSPOT_ACCOUNT_EMAIL=<HUBSPOT_ACCOUNT_EMAIL> --env MCP_WORKSPACE_PATH=<MCP_WORKSPACE_PATH> --env HUBSPOT_CLIENT_ID=<HUBSPOT_CLIENT_ID> --env HUBSPOT_CLIENT_SECRET=<HUBSPOT_CLIENT_SECRET> --transport stdio hubspot -- npx -y @mindstone/mcp-server-hubspotWhat HubSpot does
The server runs on your own machine via npx -y @mindstone/mcp-server-hubspot and hands the agent 106 tools covering CRM objects, their associations, marketing lists, files, workflows and conversations. Every record it creates carries a source label, so you can tell later which entries came from an AI agent. File uploads stay inside one workspace folder on disk.
OAuth is the host's job, not the server's. The server reads tokens the host has already written to ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json. Each process serves a single HubSpot account, so run separate processes with different HUBSPOT_ACCOUNT_EMAIL values if you need several. Node.js 20+ and npm are required.
Start it without HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET and it still boots, but any tool that touches the HubSpot API answers with a structured auth_required response. The file tools need a writable MCP_WORKSPACE_PATH directory.
What it helps with
- look up a company by name and get its ID
- log a call note on a customer record
- schedule a follow-up task tied to a deal
- attach uploaded files to CRM records
- work across several HubSpot accounts from one agent
Example prompts for the agent
- Find Acme Corp in HubSpot and log a note about the call with their CTO
- Create a task to follow up with Acme Corp next Tuesday, associated to the company
- Upload a file from the workspace and attach it to the deal record
How to install HubSpot
Platform CLI
claude mcp add --env HUBSPOT_CONFIG_DIR=<HUBSPOT_CONFIG_DIR> --env HUBSPOT_ACCOUNT_EMAIL=<HUBSPOT_ACCOUNT_EMAIL> --env MCP_WORKSPACE_PATH=<MCP_WORKSPACE_PATH> --env HUBSPOT_CLIENT_ID=<HUBSPOT_CLIENT_ID> --env HUBSPOT_CLIENT_SECRET=<HUBSPOT_CLIENT_SECRET> --transport stdio hubspot -- npx -y @mindstone/mcp-server-hubspotReplace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
codex mcp add hubspot --env HUBSPOT_CONFIG_DIR=<HUBSPOT_CONFIG_DIR> --env HUBSPOT_ACCOUNT_EMAIL=<HUBSPOT_ACCOUNT_EMAIL> --env MCP_WORKSPACE_PATH=<MCP_WORKSPACE_PATH> --env HUBSPOT_CLIENT_ID=<HUBSPOT_CLIENT_ID> --env HUBSPOT_CLIENT_SECRET=<HUBSPOT_CLIENT_SECRET> -- npx -y @mindstone/mcp-server-hubspotReplace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-hubspot"
],
"env": {
"HUBSPOT_CONFIG_DIR": "<HUBSPOT_CONFIG_DIR>",
"HUBSPOT_ACCOUNT_EMAIL": "<HUBSPOT_ACCOUNT_EMAIL>",
"MCP_WORKSPACE_PATH": "<MCP_WORKSPACE_PATH>",
"HUBSPOT_CLIENT_ID": "<HUBSPOT_CLIENT_ID>",
"HUBSPOT_CLIENT_SECRET": "<HUBSPOT_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"servers": {
"hubspot": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-hubspot"
],
"env": {
"HUBSPOT_CONFIG_DIR": "<HUBSPOT_CONFIG_DIR>",
"HUBSPOT_ACCOUNT_EMAIL": "<HUBSPOT_ACCOUNT_EMAIL>",
"MCP_WORKSPACE_PATH": "<MCP_WORKSPACE_PATH>",
"HUBSPOT_CLIENT_ID": "<HUBSPOT_CLIENT_ID>",
"HUBSPOT_CLIENT_SECRET": "<HUBSPOT_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
gemini mcp add -e HUBSPOT_CONFIG_DIR=<HUBSPOT_CONFIG_DIR> -e HUBSPOT_ACCOUNT_EMAIL=<HUBSPOT_ACCOUNT_EMAIL> -e MCP_WORKSPACE_PATH=<MCP_WORKSPACE_PATH> -e HUBSPOT_CLIENT_ID=<HUBSPOT_CLIENT_ID> -e HUBSPOT_CLIENT_SECRET=<HUBSPOT_CLIENT_SECRET> hubspot npx -y @mindstone/mcp-server-hubspotReplace <…> with your own values. 5 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about HubSpot
How do I install HubSpot in Claude Code?
Run `claude mcp add mcp-server-hubspot -e HUBSPOT_CONFIG_DIR=<HUBSPOT_CONFIG_DIR> -e HUBSPOT_ACCOUNT_EMAIL=<HUBSPOT_ACCOUNT_EMAIL> -e HUBSPOT_CLIENT_ID=<HUBSPOT_CLIENT_ID> -e HUBSPOT_CLIENT_SECRET=<HUBSPOT_CLIENT_SECRET> -- npx -y @mindstone/mcp-server-hubspot`, replacing the placeholders with your own values.
What does this MCP server do?
It gives an agent access to HubSpot CRM objects — contacts, companies, deals, tickets, leads, tasks and notes — plus properties, owners, marketing lists, workflows and files. That adds up to 106 tools.
Why do tools come back with auth_required?
The server relies on host-orchestrated OAuth and reads token files the host writes. When credentials are missing, authenticate_hubspot_account returns an auth_required response and the host opens the browser OAuth flow.
