crmport

crmport

crmport is a small workbench for a HubSpot CRM portal. It treats the CRM the way the API does: everything is an object — a contact, a company, a deal, a ticket — identified by an object type and an ID, carrying a free-form map of properties. From that one idea crmport lists objects with paging, searches them with HubSpot filter groups, reads, creates, updates, and archives them one at a time or in a batch, inspects the property definitions for a type, looks up the owners who can hold records, and reads or creates the associations that connect one object to another. One binary serves a command-line interface and a stdio MCP server.

A HubSpot private-app access token is required. Put it in the HUBSPOT_ACCESS_TOKEN environment variable; it is sent to the API as an Authorization: Bearer header and never appears in output. When the variable is missing, every call fails with an error that names it, before any request is made.

This is a core subset of the HubSpot platform: CRM objects, properties, owners, and associations. Files, forms, marketing email, blogs and CMS content, custom object schema creation, workflows, and OAuth app management are not part of this tool.

Install

npx @reneturcios/crmport list contacts --limit 10

Or run the container image:

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

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

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

Each command prints the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing HUBSPOT_ACCESS_TOKEN or an API error), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/crmport mcp

MCP client configuration:

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

Tools

Tool	Input	What it returns
hubspot_list_objects	objectType (required), limit, after, properties (optional)	A page of CRM objects of that type.
hubspot_search_objects	objectType, filterGroups (required), properties, limit, after, sorts (optional)	Objects matching the filter groups.
hubspot_get_object	objectType, objectId (required), properties (optional)	The single object.
hubspot_create_object	objectType, properties (required), associations (optional)	The created object.
hubspot_update_object	objectType, objectId, properties (required)	The updated object.
hubspot_delete_object	objectType, objectId (required)	An archive receipt; HubSpot's delete moves the object to the recycle bin.
hubspot_batch_create_objects	objectType, inputs (required)	The batch creation results.
hubspot_list_properties	objectType (required)	Property definitions for the type.
hubspot_get_owner	ownerId (required)	The owner record.
hubspot_list_owners	limit, after (optional)	A page of owners.
hubspot_list_associations	objectType, objectId, toObjectType (required), limit, after (optional)	Associations from the object to the other type.
hubspot_create_association	objectType, objectId, toObjectType, toObjectId (required), associationTypeId (optional)	The created association.

Object reads and writes use the CRM v3 endpoints under https://api.hubapi.com/crm/v3/objects/{objectType}; properties live under /crm/v3/properties/{objectType} and owners under /crm/v3/owners. Associations use the v4 endpoints under /crm/v4/objects/{objectType}/{id}/associations/{toObjectType}.

Development

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

License

MIT — see LICENSE.