crmport

crmport

crmport 是一个用于 HubSpot CRM 门户的小型工作台。它像 API 一样处理 CRM：所有内容都是对象——联系人、公司、交易、工单——由对象类型和 ID 标识，并携带自由格式的属性映射。基于这一理念，crmport 可以分页列出对象， 使用 HubSpot 筛选组搜索对象，逐个或批量读取、创建、更新和归档对象， 查看某种类型的属性定义，查找可持有记录的所有者，以及读取或创建 连接不同对象的关联。一个二进制文件同时提供命令行 界面和 stdio MCP 服务。

需要 HubSpot 私有应用访问令牌。将其放入 HUBSPOT_ACCESS_TOKEN 环境变量中；该令牌会作为 Authorization: Bearer 标头发送到 API，且绝不会出现在输出中。若 未设置此变量，每次调用都会返回指出该变量名称的错误，且不会发送任何请求。

这是 HubSpot 平台的核心子集：CRM 对象、 属性、所有者和关联。本工具不支持文件、表单、营销电子邮件、 博客和 CMS 内容、自定义对象架构创建、工作流以及 OAuth 应用管理。

安装

npx @reneturcios/crmport list contacts --limit 10

或者运行容器镜像：

docker run -i -e HUBSPOT_ACCESS_TOKEN ghcr.io/cloudcorprecords/crmport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

export HUBSPOT_ACCESS_TOKEN=<redacted>

crmport list contacts --limit 25 --properties firstname,email
crmport search contacts '[{"filters":[{"propertyName":"lastname","operator":"EQ","value":"Smith"}]}]'
crmport get contacts 12345
crmport create deals '{"dealname":"New deal","amount":"5000"}'
crmport update deals 67890 '{"amount":"7500"}'
crmport delete tickets 11111
crmport batch-create companies '[{"properties":{"name":"Acme"}}]'
crmport properties contacts
crmport owner 22222
crmport owners --limit 10
crmport associations contacts 12345 companies
crmport associate contacts 12345 companies 99999 --type-id 1

crmport --version

每条命令都会输出上游 JSON 负载。退出码：成功时为 0， 调用失败时为 1（包括缺少 HUBSPOT_ACCESS_TOKEN 或 API 错误），用法错误时为 2。

MCP 服务

一个二进制文件提供这两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/crmport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "crmport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/crmport", "mcp"],
      "env": { "HUBSPOT_ACCESS_TOKEN": "pat-..." }
    }
  }
}

工具

工具	输入	返回内容
hubspot_list_objects	objectType（必填）、limit、after、properties（可选）	该类型的一页 CRM 对象。
hubspot_search_objects	objectType、filterGroups（必填）、properties、limit、after、sorts（可选）	符合筛选组条件的对象。
hubspot_get_object	objectType、objectId（必填）、properties（可选）	单个对象。
hubspot_create_object	objectType、properties（必填）、associations（可选）	创建的对象。
hubspot_update_object	objectType、objectId、properties（必填）	更新后的对象。
hubspot_delete_object	objectType、objectId（必填）	归档回执；HubSpot 的删除操作会将对象移至回收站。
hubspot_batch_create_objects	objectType、inputs（必填）	批量创建结果。
hubspot_list_properties	objectType（必填）	该类型的属性定义。
hubspot_get_owner	ownerId（必填）	所有者记录。
hubspot_list_owners	limit、after（可选）	一页所有者。
hubspot_list_associations	objectType、objectId、toObjectType（必填）、limit、after（可选）	从该对象指向另一类型对象的关联。
hubspot_create_association	objectType、objectId、toObjectType、toObjectId（必填）、associationTypeId（可选）	创建的关联。

对象的读取和写入使用 CRM v3 端点 https://api.hubapi.com/crm/v3/objects/{objectType}；属性位于 /crm/v3/properties/{objectType} 下，所有者位于 /crm/v3/owners 下。关联使用 /crm/v4/objects/{objectType}/{id}/associations/{toObjectType} 下的 v4 端点。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 详见 LICENSE。