·

HubSpot MCP với Claude Code CLI and VS Code

Cài đặt HubSpot MCP trong Claude Code CLI and VS Code để AI agent có thể quản lý contact, deal và ticket ngay trong trình soạn thảo.

Claude Code (CLI chạy trực tiếp trong terminal, và extension chạy trong VS Code) xử lý tool calling khá mạch lạc, phù hợp để biến việc "đào dữ liệu CRM" từ một tác vụ thủ công tốn cả buổi thành vài câu prompt có kết quả trong vài phút. Vì bản chất công việc ở đây là research và tổng hợp (không phải sửa code), Claude Code với khả năng suy luận tốt trên văn bản dài (ticket, note, email log) là lựa chọn hợp lý. Bài này hướng dẫn cài đặt, cách truy vấn deal/ticket/contact hiệu quả từ terminal, và — quan trọng nhất với engineer — cách biến tín hiệu từ sales/support thành requirement sản phẩm có thể đưa vào backlog ngay.

Cài Đặt và Kết Nối HubSpot MCP Với Claude Code

Thêm HubSpot MCP server bằng lệnh claude mcp add:

claude mcp add hubspot \
  --env "PRIVATE_APP_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -- npx -y @hubspot/mcp-server

Hoặc cấu hình qua file .mcp.json ở root repo (phù hợp khi muốn chia sẻ config cho cả team qua git, không chia sẻ token):

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@hubspot/mcp-server"],
      "env": {
        "PRIVATE_APP_ACCESS_TOKEN": "${HUBSPOT_TOKEN}"
      }
    }
  }
}

Đặt HUBSPOT_TOKEN trong .env local hoặc secret của CI, không commit token thật lên git dù repo là private — đây là thói quen bảo mật cơ bản, càng quan trọng hơn với token có quyền đọc dữ liệu khách hàng.

Xác nhận kết nối bằng claude mcp list, kỳ vọng thấy hubspot: connected. Với VS Code extension, mở Command Palette, tìm "Claude Code: MCP Servers" để xem trạng thái tương tự dưới dạng UI.

Mẹo: Chạy thử một truy vấn đọc rất nhỏ ngay sau khi cài, ví dụ "lấy thông tin 1 company bất kỳ trong HubSpot của tôi", trước khi giao việc phức tạp. Nếu bước này lỗi 403, gần như chắc chắn do thiếu scope khi tạo Private App, chưa liên quan gì đến cách bạn prompt.

Truy Vấn Deals, Tickets và Hoạt Động Contact Từ Terminal

Claude Code phù hợp để dùng như một "CLI cho HubSpot" khi bạn đang trong terminal xử lý task kỹ thuật và không muốn mở browser chuyển qua CRM UI.

Ví dụ truy vấn deal đang ở giai đoạn cuối pipeline:

Lấy tất cả deal ở dealstage "Contract Sent" hoặc "Negotiation",
sắp theo amount giảm dần, in dạng bảng: Deal name, Amount, Owner, Close date dự kiến.

Ví dụ truy vấn hoạt động gần đây của một contact cụ thể (hữu ích trước một buổi demo kỹ thuật):

Lấy toàn bộ engagement (email, call, meeting) của contact có email
"cto@acme-corp.com" trong 60 ngày qua, sắp theo thời gian, tóm tắt
mỗi engagement 1 câu.

Ví dụ truy vấn kết hợp nhiều object — đây là nơi Claude Code thể hiện rõ giá trị vì nó tự lên kế hoạch gọi nhiều tool liên tiếp:

Với mỗi deal đang "at risk" (không có hoạt động nào trong 14 ngày qua),
lấy company liên kết và ticket support đang mở của company đó (nếu có).
In ra danh sách: Deal name, Ngày hoạt động cuối, Ticket đang mở liên quan (nếu có).

Claude Code sẽ tự gọi search-objects cho deals theo điều kiện thời gian hoạt động, list-associations để lấy company, rồi search-objects cho tickets — bạn chỉ cần diễn đạt đúng tiêu chí, không cần biết trình tự tool.

Mẹo: Với truy vấn có điều kiện thời gian ("60 ngày qua", "không hoạt động 14 ngày"), luôn nêu rõ mốc ngày tuyệt đối nếu có thể thay vì chỉ nói tương đối — ví dụ thêm "tính từ hôm nay [ngày cụ thể]" — vì một số phiên bản MCP server không tự biết ngày hiện tại chính xác nếu không được truyền vào context.

Biến Tín Hiệu Sales và Support Thành Yêu Cầu Sản Phẩm

Đây là use case mang lại giá trị rõ nhất cho một senior engineer hoặc tech lead làm việc gần với sản phẩm: bạn có dữ liệu thô (ticket, note sales) nhưng cần một requirement có cấu trúc để đưa vào backlog.

Quy trình thực tế gồm 3 bước, làm trực tiếp trong một session Claude Code:

Bước 1 — Thu thập và nhóm theo chủ đề:

Lấy toàn bộ ticket "Open" hoặc "Waiting on us" tạo trong 45 ngày qua
trong pipeline "Customer Support". Nhóm theo chủ đề chính, mỗi nhóm liệt
kê số lượng ticket và ticket ID đại diện.

Bước 2 — Đào sâu vào nhóm có volume cao nhất, đối chiếu revenue impact:

Với nhóm chủ đề có số ticket cao nhất ở trên, lấy company liên kết của
từng ticket, cộng tổng deal amount hiện tại của các company đó (chỉ tính
deal đang "Closed Won" hoặc active). Việc này giúp biết vấn đề ảnh hưởng
tới bao nhiêu doanh thu thực tế, không chỉ số lượng ticket.

Bước 3 — Sinh requirement doc theo cấu trúc chuẩn của team:

Từ dữ liệu vừa phân tích, viết một requirement draft gồm:
- Problem statement (1 đoạn, dựa trên nội dung ticket thật, có quote)
- Impact (số ticket, số company, tổng revenue liên quan)
- Đề xuất 2 hướng giải quyết ở mức concept (không cần chi tiết kỹ thuật)
- Câu hỏi còn mở cần hỏi thêm sales/support trước khi estimate
Không tự quyết định hướng nào nên làm — chỉ trình bày để tôi và PM cùng review.

Cách làm này biến một quy trình "đọc ticket bằng tay, cảm tính chọn ưu tiên" thành một bản requirement có số liệu hỗ trợ — dễ bảo vệ hơn nhiều khi trình bày trong buổi planning.

Mẹo: Luôn yêu cầu Claude Code trình bày "câu hỏi còn mở" như một mục riêng thay vì để nó tự suy đoán và điền vào cho đủ. Requirement thiếu thông tin mà bị AI tự lấp đầy bằng suy luận hợp lý nhưng sai thực tế nguy hiểm hơn nhiều so với để trống và hỏi lại người liên quan.

Các Mẫu Prompt Để Truy Vấn CRM An Toàn, Có Giới Hạn Phạm Vi

Vì dữ liệu HubSpot chứa thông tin khách hàng thật, nên có vài pattern prompt nên áp dụng thành thói quen, không chỉ tùy hứng theo từng lần hỏi:

Pattern 1 — Luôn giới hạn phạm vi theo thời gian hoặc theo object cụ thể. Tránh prompt kiểu "lấy tất cả ticket" — luôn có điều kiện lọc (theo ngày, theo pipeline, theo company).

Pattern 2 — Yêu cầu ẩn PII khi output sẽ được chia sẻ rộng.

Tổng hợp top 5 chủ đề complaint tháng này thành báo cáo để đăng vào
Slack channel #product-updates. Chỉ dùng ticket ID và nội dung tóm tắt,
không kèm tên/email khách hàng trong báo cáo.

Pattern 3 — Yêu cầu agent nêu rõ tool nào đã gọi và filter nào đã dùng, đặc biệt với truy vấn phức tạp nhiều bước — giúp bạn xác minh nhanh agent có hiểu đúng phạm vi bạn muốn hay không.

Pattern 4 — Tách rõ giai đoạn "đọc để phân tích" và "ghi note lại kết luận". Nếu muốn agent lưu kết quả phân tích vào HubSpot dưới dạng note, luôn yêu cầu xác nhận nội dung trước khi ghi:

Trước khi tạo note vào deal "Acme Corp - Enterprise", cho tôi xem nội
dung note dự kiến để duyệt.

Mẹo: Viết sẵn các pattern trên thành một section trong CLAUDE.md của repo (ví dụ "quy tắc truy vấn HubSpot MCP") — Claude Code tự đọc file này ở đầu mỗi session, giúp cả team áp dụng nhất quán mà không cần nhắc lại từng lần.

Mẹo Thực Chiến Khi Dùng HubSpot MCP Với Claude Code

  • Bắt đầu mọi truy vấn phức tạp bằng một câu hỏi hẹp để kiểm tra agent hiểu đúng field/scope trước khi giao task tổng hợp lớn.
  • Với VS Code extension, dùng panel MCP để xem log request/response khi cần debug — nhanh hơn nhiều so với đoán qua câu trả lời text thuần.
  • Định kỳ (1-2 tuần đầu) review lại các báo cáo/requirement do AI tạo để hiệu chỉnh prompt pattern, sau đó lưu pattern hoạt động tốt vào CLAUDE.md.
  • Theo dõi rate limit HubSpot API khi chạy các truy vấn tổng hợp nhiều object liên tiếp — nếu gặp lỗi 429, yêu cầu agent chia nhỏ truy vấn thành nhiều lượt thay vì gọi dồn.

Mẹo: Ghi lại các prompt mẫu đã chứng minh hiệu quả (research trước cuộc gọi, tổng hợp complaint theo chủ đề, sinh requirement draft) thành một "runbook" trong repo — coi đây là chuẩn chung giúp mọi engineer trong team khai thác HubSpot MCP theo cùng cách, giảm thời gian dò lại prompt từ đầu.

Tiếp HubSpot MCP với OpenCode