# HubSpot: how to read it into Maplith

*CRM · also known as HubSpot CRM, HubSpot Sales Hub, HubSpot Marketing Hub, HubSpot Service Hub · last checked 2026-10-20 · recipe `maplith://systems/hubspot`*

HubSpot holds the company's contacts, companies, deals and sales activities, plus the products and line items on each deal.

## Best path

**Recommended: your agent fetches it.** HubSpot has its own connectors in both Claude and ChatGPT, and a small company adds only hundreds of deals and contacts a month, so the customer's agent can read what the map needs with access it already has. A full contact list in the tens of thousands is cheaper as an export file.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: HubSpot connector in Claude; HubSpot app in ChatGPT. The agent uses the HubSpot connector to read the fields and recent records of contacts, companies, deals and line items, and how they are associated. It only reads; it should not use the connector's create or update tools.
2. **Maplith reads an MCP server your human already has.** Official: **HubSpot remote MCP server**. Endpoint to connect to: `https://mcp.hubspot.com`. Documentation (a page to read, not an address to connect to): https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server. Access: There is no separate read-only token. A HubSpot admin creates an MCP connector under Development, MCP Connectors, and each person then signs in to HubSpot and approves access. The server sees only what that HubSpot user may see, so connect with a user whose HubSpot permissions are limited. It has both read and write tools (many write tools ask for confirmation first). Products, line items, invoices and other revenue objects are marked beta, and activities are blocked when Sensitive Data is turned on. HubSpot's separate developer MCP server runs in the HubSpot CLI and is for building apps, not for reading CRM data. Maplith cannot read this server: it offers tools or a personal sign-in to an agent, not resources Maplith reads. Maplith reads only a server that serves MCP resources and takes a token a person types under Data sources › Systems in the Maplith app, such as the customer-run template for a database (ADR-0028). Your human can connect this server to you instead, as path 1.
3. **Export files**, the fallback that always works: see *Export steps* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Contacts | One person the company sells to or talks to. | record id, email (Maplith tries to mask it), associated company id, contact owner, lifecycle stage, create date | Webshop customers and helpdesk tickets by email; accounting customers through the associated company. |
| Companies | One customer or prospect organisation. | record id, company domain name, company name, VAT or CVR number (only if the company added that property), company owner | Accounting customers by VAT or CVR number or by name; contacts and email by company domain. |
| Deals | One sales opportunity in a pipeline. | record id, pipeline, deal stage, amount, close date, associated company id, associated contact id, deal owner | Companies and contacts by associated record id; invoices in the accounting system or Stripe by a deal or order reference, if the company records one. |
| Line items and products | One product or service line on a deal, linked to the product library. | line item id, associated deal id, product id, SKU, quantity, unit price | Deals by deal id; webshop and accounting products by SKU. |
| Activities | One logged call, email, meeting, note or task. | activity id, activity type, activity date, associated contact id, associated company id, associated deal id, owner | Contacts, companies and deals by associated record id; shows how fast leads and deals are followed up. |
| Contact-company associations | One contact-to-company association, projected as fromObjectId and toObjectId from the association response. | fromObjectId, toObjectId | Contacts and companies by their object ids. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Declared joins and identifier formats

Vendor documentation states these keys; Maplith checks them against the shared exports. A declaration is not a confirmation.

- Contact-company associations.contact_id → Contacts.id (N:1). Source: https://developers.hubspot.com/docs/api-reference/latest/crm/associations/associate-records/guide
- Contact-company associations.company_id → Companies.id (N:1). Source: https://developers.hubspot.com/docs/api-reference/latest/crm/associations/associate-records/guide

## Structure artefacts

- **HubSpot field definitions** (data_dictionary; structure-only form): Ask your agent for the property names, field types and association definitions for the shared objects. Remove record values, defaults and examples; keep only the structure projection. Source: https://developers.hubspot.com/docs/api-reference/legacy/crm/properties/guide

Share structure only: no examples, rows, credentials or pinned data. Your human chooses what to send.

## Read-only access

**Who usually has the rights:** Usually the HubSpot Super Admin, often the owner or the sales lead. Turning on the connector in Claude or ChatGPT needs a Super Admin or a user with App Marketplace permissions.

**For the key your own agent's client uses, choose only these read permissions:** `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read`, `crm.objects.line_items.read`, `crm.objects.owners.read`, `crm.objects.quotes.read`, `crm.objects.invoices.read`, `crm.schemas.contacts.read`, `crm.schemas.companies.read`, `crm.schemas.deals.read`

**Where to click:**

1. In HubSpot, go to Development
2. In the left sidebar, click Legacy apps
3. Click Create legacy app, then choose Private
4. On the Basic Info tab, give the app a name
5. Open the Scopes tab and click Add new scope
6. Tick only the read scopes listed here, then click Update
7. Click Create app, then Continue creating
8. Keep the app's access token in the tool that will read HubSpot for you; never paste it into a chat, and Maplith never asks for it

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app, and only for an MCP server it can read.

## Export steps

**Format:** CSV · **Date range:** All records for contacts and companies; deals from the last 12 months

1. Go to CRM, then Contacts (or Companies, or Deals)
2. Open the All contacts view (or All companies, All deals) to include every record
3. Click Export at the top right of the table (for deals in board view: Board options, then Export view)
4. Choose CSV as the file format; click Customize to pick all properties and to include associations
5. Click Export and open the download link HubSpot sends by email
6. Activities such as calls and notes are not in record exports; ask the agent or use activity reports for those

## Volume hint

**About 100–2,000 new contacts; 20–200 new deals a month** (an estimate). Estimate for a small company, not a measured figure: a few sales people, with contacts growing faster than deals because of forms and email.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-20:

- https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server
- https://www.hubspot.com/ai-tools/claude-connector
- https://knowledge.hubspot.com/integrations/connect-your-hubspot-account-to-chatgpt
- https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview
- https://developers.hubspot.com/docs/apps/legacy-apps/authentication/scopes
- https://knowledge.hubspot.com/import-and-export/export-records
- https://knowledge.hubspot.com/properties/hubspots-default-contact-properties
- https://knowledge.hubspot.com/da/properties/hubspots-default-contact-properties
- https://knowledge.hubspot.com/da/import-and-export/export-records
- https://developers.hubspot.com/docs/api-reference/latest/crm/exports/guide
- https://developers.hubspot.com/docs/api-reference/latest/crm/associations/associate-records/guide
- https://developers.hubspot.com/docs/api-reference/legacy/crm/properties/guide