HubSpot Custom Objects MCP Server

HubSpot's official MCP server went GA in April 2026. It still doesn't support Custom Objects.

If your portal runs on custom objects Sites, Service Actions, Properties, Vehicles, Subscriptions, whatever your business actually revolves around Claude and every other MCP client is blind to them. The official server at mcp.hubspot.com/mcp covers contacts, companies, deals, and tickets. Everything you built to model your real business is invisible.

This server fills that exact gap. Run it alongside the official one: HubSpot's handles standard objects, this one handles every 2-XXXXXXXXX custom object in your portal.

┌─────────────┐     ┌──────────────────────────┐
│             │────▶│ mcp.hubspot.com/mcp      │  contacts, companies, deals
│  Claude /   │     │ (official)               │
│  MCP client │     └──────────────────────────┘
│             │     ┌──────────────────────────┐
│             │────▶│ this server              │  ← your custom objects
└─────────────┘     └──────────────────────────┘

---

What you get

Six tools, covering full custom-object CRUD:

Tool	What it does
list_custom_object_schemas	Discovers every custom object in the portal IDs, labels, required and available properties. Always called first.
search_custom_objects	Filter, sort, and page through records with HubSpot's full search grammar.
get_custom_object_record	One record by HubSpot ID or by any unique property.
batch_get_custom_object_records	Up to 100 records in a single call.
create_custom_object_record	New record, with optional associations to contacts/companies/deals.
update_custom_object_record	Partial update untouched fields stay untouched.

Built for LLM use, not just API parity: schema discovery is self-describing, 429s come back as "wait N seconds" instead of a stack trace, and every tool refuses standard-object IDs with a pointer to the right server.

---

Quickstart

Requires Python 3.12+, plus a HubSpot API credential with these scopes:

crm.schemas.custom.read
crm.objects.custom.read
crm.objects.custom.write

Use a Service Key HubSpot's current credential for system-to-system integrations (public beta since Feb 2026). Create one at Settings → Integrations → Service Keys, or Development → Keys → Service Keys in the sidebar. A key can only be granted scopes the creating user already has, and it can be rotated without rebuilding anything.

<details> <summary>Using a legacy Private App token instead?</summary>

That works too no changes needed. Private apps still function, but HubSpot now classifies them as legacy and steers new integrations to Service Keys. Create one at Settings → Integrations → Private Apps.

Both credentials are pat-na1-… bearer tokens sent in the same Authorization header, so this server accepts either in HUBSPOT_ACCESS_TOKEN without a config change. Service Keys don't support webhooks irrelevant here, since this server only makes outbound REST calls.

</details>

Windows (PowerShell)

py -m venv venv
./venv/Scripts/activate
pip install -r requirements.txt
$env:HUBSPOT_ACCESS_TOKEN = "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
python server.py

macOS / Linux

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
python server.py

Server comes up on http://localhost:8000/mcp, with a health endpoint at /health.

Tip: instead of exporting the token every session, copy .env.example to .env and fill it in it's loaded automatically at startup, and .gitignore already keeps it out of git.

If PowerShell blocks activate with an execution-policy error, run: Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

venv/ is gitignored, so it won't follow you to GitHub when you deploy.

Connect your MCP client

{
  "mcpServers": {
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com/mcp",
    },
    "hubspot-custom-objects": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
    },
  },
}

Then ask: "What custom objects exist in my HubSpot portal?" the model calls list_custom_object_schemas and takes it from there.

---

Testing against a real portal

Custom objects are an Enterprise-tier feature. If your portal isn't Enterprise you won't be able to create one use a free developer test account instead: up to 10 accounts, each with a 90-day trial of Enterprise features, and no real data at risk. (They expire after 90 days without API calls; any call renews them.)

dev_seed.py creates a throwaway custom object and exercises every tool:

python dev_seed.py seed      # create "MCP Test Site" + 3 sample records
python dev_seed.py smoke     # call all 6 tools against the live portal
python dev_seed.py cleanup   # delete the records, then the schema

seed and cleanup need one extra scope beyond the server's own: crm.schemas.custom.write. The smoke run needs only the three standard scopes.

The seeded object is built to cover the awkward paths, not just the happy one site_code is a unique property, so smoke verifies lookup by id_property on both the single-record and batch tools, checks that filtered search returns only matching rows, and re-reads after updating to confirm the write actually persisted rather than trusting the echoed response.

dev_seed.py is a local harness, not part of the server. Delete it before publishing if you'd rather keep the repo to the 7 shipped files.

---

Deploy to Prefect Horizon

Horizon is the managed MCP hosting platform built by the FastMCP team, with a free personal tier. No containers to build and no infra config to write it deploys straight from your GitHub repo and gives you built-in OAuth, so only authenticated users in your org can reach the server.

1. Push this repo to GitHub (public or private).
2. Sign in at horizon.prefect.io with GitHub and pick the repo.
3. Set the entrypoint to server.py:mcp same syntax as fastmcp run.
4. Add HUBSPOT_ACCESS_TOKEN as an environment variable in the server's config.
5. Toggle authentication on, and hit Deploy. Builds typically finish in under 60 seconds.

You get a URL like https://your-server-name.fastmcp.app/mcp. Drop it into the client config above in place of localhost:

"hubspot-custom-objects": {
  "type": "http",
  "url": "https://your-server-name.fastmcp.app/mcp"
}

Dependencies are detected automatically from requirements.txt. Pushes to the repo redeploy the server. The if __name__ == "__main__" block in server.py is ignored by Horizon it's there so python server.py still works locally.

<details> <summary>Self-hosting with Docker instead</summary>

A Dockerfile is included if you'd rather run it yourself:

docker build -t hubspot-custom-objects-mcp .
docker run -p 8000:8000 -e HUBSPOT_ACCESS_TOKEN="pat-na1-..." hubspot-custom-objects-mcp

Point your platform's health check at /health (returns 200 {"status":"ok",...}), not /mcp. A bare GET /mcp returns 406 the streamable-HTTP transport requires an SSE Accept header and a JSON-RPC body which most platforms read as unhealthy.

Self-hosting means you own the auth problem that Horizon solves for you; see Security notes.

</details>

---

Configuration

Variable	Default	Purpose
HUBSPOT_ACCESS_TOKEN	(required)	Service Key, or legacy Private App token.
HOST	0.0.0.0	Bind address.
PORT	8000	HTTP port.
HUBSPOT_SCHEMAS_API_VERSION	2026-03	Pin the dated object-schemas API version.

---

Security notes

The token is portal-wide and write-capable. Treat it like a password:

• Anyone who can reach /mcp can write to your CRM. Enable Horizon's authentication so only your org can connect. If you self-host, put it on a private network or add an auth proxy there is no auth on the MCP endpoint itself.
• Never commit .env. Set HUBSPOT_ACCESS_TOKEN as an environment variable on your host, not in the repo.
• Grant the key only the three custom-object scopes listed above nothing else.
• Prefer a Service Key over a legacy private app: it can be rotated in place, so a leak doesn't mean rebuilding the integration.
• Two different auth layers, don't conflate them: Horizon's OAuth controls who can reach this server. The HubSpot side is a single portal-wide key no OAuth 2.1, no multi-tenancy. One deployment, one portal, and every user shares that key's access.

---

Limitations

• Custom objects only, by design. Standard objects are the official server's job.
• No delete tool deliberately omitted so an LLM can't destroy records. Add one if you want it.
• No association management beyond setting associations at creation time.
• Search results are capped by HubSpot at 10,000 records per query; page with next_after.

---

License

MIT. Fork it, ship it, sell it.

---

Want it tailored to your portal? DM me on Linkedin or email me here (saad.k.dev@gmail.com) I build custom HubSpot integrations.