AI导哈

HubSpot CRM API命令行工具

一个专为HubSpot CRM API设计的JSON优先、代理原生命令行工具，支持通过终端或MCP工具管理CRM数据。

  • by bcharleson
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 bcharleson/hubspot-cli

使用说明

HubSpot命令行界面

JSON-首先，用于HubSpot CRM API的代理名CLI。

HubSpot有一个官方CLI(@hubspot/cli)--但它仅涵盖CMS开发工具（设计管理器、无服务器功能、HubDB）。有 没有针对CRM API的官方CLI：联系人、公司、交易、门票、管道、所有者、约定或协会。

此CLI填补了这一空白。每个命令都返回结构化JSON，从终端工作 和 作为MCP工具，您的AI代理可以像人类从命令行一样管理整个HubSpot CRM。

为什么选择Agent Native？

@hubspot/cli （官方） hubspot-cli （这个）
范围 仅CMS（主题、模块、无服务器） 完整的CRM API-11个组中的55个命令
输出 人类可读文本 JSON优先——默认情况下机器可解析
MCP支持 否 内置MCP服务器——每个命令都是MCP工具
代理使用 不是为代理设计的 每个命令在终端或MCP上的工作方式都是相同的
认证 OAuth/个人访问密钥 私有应用访问令牌（3层分辨率）

本地代理 指：

  • JSON第一个输出 --每个响应都是有效的JSON，管道到 jq 或从任何语言中消费
  • 双入口点 --与CLI相同的命令 和 零自适应MCP工具
  • 结构化错误 --错误返回 { "error": "...", "code": "..." }，不是堆栈跟踪
  • 字段过滤 — --fields id,properties.email 只返回您需要的东西
  • 自动化中没有交互式提示 --所有可用作标志、环境变量或配置的参数

安装

npm install -g hubspot-cli

快速开始

# 1. Create a Private App access token in HubSpot
# Settings -> Integrations -> Private Apps -> Create a private app

# 2. Authenticate with the token
export HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxx

# List contacts
hubspot contacts list --pretty

# Create a contact
hubspot contacts create --email "john@acme.com" --firstname "John" --lastname "Doe"

# Search deals
hubspot deals search --query "acme" --pretty

# Get pipeline stages
hubspot pipelines stages <pipeline-id> --object-type deals

认证

1.创建私有应用访问令牌

  1. 在HubSpot，请访问 设置 → 集成 → 私人应用程序 → 创建私人应用程序
  2. 在 基本信息 选项卡，为其命名，例如 hubspot-cli-agent
  3. 在 范围 选项卡中，添加您计划使用的命令组的作用域：
命令组 需要范围
contacts crm.objects.contacts.read + crm.objects.contacts.write
companies crm.objects.companies.read + crm.objects.companies.write
deals crm.objects.deals.read + crm.objects.deals.write
tickets tickets
owners crm.objects.owners.read
engagements （电子邮件阅读） sales-email-read 只有当你需要阅读电子邮件正文时
lists crm.lists.read + crm.lists.write
properties crm.schemas.contacts.read + crm.schemas.contacts.write, crm.schemas.companies.read + crm.schemas.companies.write, crm.schemas.deals.read + crm.schemas.deals.write
  1. 点击 创建应用
  2. 打开 认证 选项卡，单击 显示令牌，并复制访问令牌。它始于 pat-na1- 接下来是您所在的地区。

2.身份验证

三层分辨率（最高优先级优先）：

# Option A: Environment variable (recommended for agents)
export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxx"

# Option B: Interactive login (saves to ~/.hubspot-cli/config.json)
hubspot login

# Option C: Per-command flag
hubspot contacts list --access-token "pat-na1-xxxxx"

3.验证

hubspot contacts list --limit 1 --pretty

命令

CRM对象（55个命令）

组 命令
联系人 list, get, create, update, delete, search, merge
公司 list, get, create, update, delete, search
交易 list, get, create, update, delete, search
票 list, get, create, update, delete, search
所有者 list, get
管道 list, get, stages
参与 create-note, create-email, create-call, create-task, create-meeting, list, get, delete
协会 list, create, delete
列表 list, get, create, update, delete, add-members, remove-members, get-members
属性 list, get, create, update, delete
搜索 run （通用跨对象搜索）

身份验证与配置

命令 描述
login 使用访问令牌进行身份验证
logout 删除存储的凭据
status 显示当前身份验证+帐户信息

MCP 服务器

# Start as MCP server (stdio transport)
hubspot mcp

每个命令都注册为MCP工具。在Claude Desktop、OpenClaw或任何MCP兼容代理中配置：

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["hubspot-cli", "mcp"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxx"
      }
    }
  }
}

或者使用本地安装：

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

全局选项

--access-token <token>  Override stored auth
--output <format>       json (default) or pretty
--pretty                Shorthand for --output pretty
--quiet                 Suppress output, exit codes only
--fields <fields>       Comma-separated field filter (supports nested: properties.email)

示例

# List contacts with specific fields
hubspot contacts list --fields id,properties.email,properties.firstname

# Search companies by name
hubspot companies search --query "acme" --properties name,domain,industry --pretty

# Create a deal in a pipeline stage
hubspot deals create --dealname "Acme Enterprise" --amount "50000" \
  --pipeline "<pipeline-id>" --dealstage "<stage-id>"

# Get all deal pipelines with stages
hubspot pipelines list --object-type deals --pretty

# Log a note
hubspot engagements create-note --body "Discovery call — interested in enterprise plan"

# Create a follow-up task
hubspot engagements create-task --subject "Send proposal" --status NOT_STARTED --priority HIGH

# Associate a contact with a company
hubspot associations create --from-type contacts --from-id 123 \
  --to-type companies --to-id 456 --type-id 1

# Manage a list
hubspot lists create --name "VIP Customers" --processing-type MANUAL
hubspot lists add-members <list-id> --record-ids "123,456"

# Create a custom property
hubspot properties create --object-type contacts --name "lead_score" \
  --label "Lead Score" --type number --field-type number --group contactinformation

# Universal search across any object type
hubspot search run --object-type deals \
  --filter '{"filters":[{"propertyName":"amount","operator":"GT","value":"10000"}]}' \
  --properties dealname,amount,dealstage

# Pipe to jq
hubspot contacts list | jq '.results[].properties.email'

建筑

此CLI遵循与以下相同的元数据驱动架构 即时cli （156个命令）和 粘土gtm-cli:

  • 命令定义 --单个结构驱动CLI注册和MCP工具注册
  • Zod模式 --CLI和MCP之间共享输入验证
  • CRM对象工厂 — createCrmObjectCommands() 生成CRUD+搜索任何HubSpot对象类型
  • 瘦REST客户端 --约130行，基于光标的分页，429秒的指数回退
  • 双入口 — dist/index.js （CLI）和 dist/mcp.js （MCP服务器）

许可证

麻省理工学院

相关 MCP