An open-source Model Context Protocol server that allows Claude to read and write HubSpot CRM data.

Note: HubSpot now ships an official MCP connector. This repository predated it and demonstrates the protocol and tool design from first principles. The intent is to show that I can build marketing-stack infrastructure, not only configure existing tools.

The context

Marketing platforms expose extensive APIs, but they are typically accessed through dashboards or spreadsheets rather than conversational interfaces. The result is that routine analytical questions — pipeline coverage, contact segmentation, owner workload — require navigating through several screens or asking an analyst to assemble a spreadsheet.

MCP — the Model Context Protocol Anthropic shipped in late 2024 — is the protocol that closes that loop: it standardizes how AI assistants (Claude, Cursor, others) call external tools. If you write an MCP server for HubSpot, suddenly Claude can answer "what's the total amount in Sales Qualified, sorted by owner" against your real data.

So I wrote one. It's on GitHub: daniel54269/hubspot-mcp.

What it does

Read tools (always on):

• search_contacts, get_contact — search + fetch with property filters and lifecycle-stage matches
• list_deals, get_deal, list_pipelines, pipeline_summary — pipeline-grade deal queries with stage roll-ups
• search_companies, get_company — same shape for companies
• recent_engagements — notes / calls / meetings / emails / tasks
• list_owners — so Claude can map owner IDs back to humans
• list_email_campaigns — open / click stats for Marketing Hub Pro+ portals

Write tools (opt-in via HUBSPOT_MCP_ALLOW_WRITES=true):

• update_contact — patch one or many properties (great for moving lifecycle stages)
• create_note — drop a note on a contact, deal, or company with auto-association

Architecture decisions

Typed HubSpot client, no SDK. HubSpot's first-party Node SDK is 1.5 MB and pulls in a lot. I wrote a 70-line wrapper around fetch that types only the fields these tools actually use. Smaller install, less surface, clearer code.

One file per tool family. tools/contacts.ts, tools/deals.ts, etc. Each file exports registerXTools(server, hs). Adding a tool is "drop a function and import it" — same pattern as adding a route in a small Express app. Easy to fork and extend.

Writes are off by default. The env var has to be flipped explicitly. Lets a marketer install the server for read-only "ask my pipeline" use without worrying about Claude updating records.

Zod schemas for every tool input. MCP clients see clean JSON schemas; Claude gets actually-validated inputs at the boundary; bad calls fail loud, not silent.

Pure stdio transport. The Claude Desktop / Cursor standard. No web server, no auth proxy, no Docker. npx -y hubspot-mcp and it works.

Why this engagement matters

The clearest demonstration of marketing engineering capability is a working artifact. An open-source MCP server against a major marketing platform is a more substantive proof of skill than a list of platforms used in past roles. The README documents the install path; the 13 tools form the product surface; the codebase is available for review on GitHub.

Try it

npm install -g hubspot-mcp
# then add to claude_desktop_config.json — instructions in the repo README

→ github.com/daniel54269/hubspot-mcp