# 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

```bash
npx @reneturcios/crmport list contacts --limit 10
```

Or run the container image:

```bash
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

```bash
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:

```bash
npx -y @reneturcios/crmport mcp
```

MCP client configuration:

```json
{
  "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

```bash
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`.