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
--object-type deals认证
1.创建私有应用访问令牌
- 在HubSpot，请访问 设置 → 集成 → 私人应用程序 → 创建私人应用程序
- 在 基本信息 选项卡，为其命名，例如
hubspot-cli-agent - 在 范围 选项卡中，添加您计划使用的命令组的作用域：
| 命令组 | 需要范围 |
|---|---|
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 |
- 点击 创建应用
- 打开 认证 选项卡，单击 显示令牌，并复制访问令牌。它始于
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 Override stored auth
--output json (default) or pretty
--pretty Shorthand for --output pretty
--quiet Suppress output, exit codes only
--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 "
" --dealstage ""
# 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
--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注册和MCP工具注册
- Zod模式 --CLI和MCP之间共享输入验证
- CRM对象工厂 —
createCrmObjectCommands()生成CRUD+搜索任何HubSpot对象类型 - 瘦REST客户端 --约130行，基于光标的分页，429秒的指数回退
- 双入口 —
dist/index.js（CLI）和dist/mcp.js（MCP服务器）
许可证
麻省理工学院