Contexte : pourquoi tu veux ce tuto maintenant

Depuis le 13 avril 2026, HubSpot heberge un serveur MCP officiel a mcp.hubspot.com. Plus besoin de wrapper, plus besoin de Zapier intermediaire : tout client MCP-compatible (Claude Desktop, ChatGPT Apps SDK, Cursor, Vercel AI SDK...) peut directement lire et ecrire ton CRM HubSpot via OAuth 2.1.

Et c'est le moment ou les RevOps Managers commencent a vouloir tester. Sans tutoriel pratique, beaucoup tatonnent : OAuth, scopes, choix client, premier prompt. Cet article passe en revue le setup complet pour un usage Claude Desktop, le plus rapide a configurer.

Si tu veux le pourquoi strategique (architecture MCP, comparatif vs API, cas d'usage RevOps), va voir notre guide MCP pour le RevOps de 65 pages. Cet article-ci est focus execution.

Prerequis

HubSpot : compte Pro ou Enterprise (le MCP server n'est pas disponible sur Starter/Free)
Permissions admin sur ton portail HubSpot (necessaire pour generer le client OAuth)
Claude Desktop installe (Mac, Windows, Linux) avec un compte Claude Pro ou Team
Un editeur de texte pour modifier le fichier de config Claude Desktop
30 minutes devant toi (compte 45 si premiere fois)

Activer MCP cote HubSpot

Dans HubSpot, va dans Settings » Integrations » MCP server. Si tu ne vois pas cette section, ton compte n'est probablement pas Pro/Enterprise ou la feature n'est pas encore deployee sur ton portail (deploiement progressif Q2 2026).

Clique « Enable MCP server ». Tu vois apparaitre l'URL de ton serveur :

https://mcp.hubspot.com/v1/{your-portal-id}

Garde ce portal ID sous la main, tu en auras besoin a l'etape 3.

Generer un client OAuth

Toujours dans Settings, va dans Integrations » Private apps puis Create a private app. Nomme-la « Claude MCP - {your-name} ».

Onglet Scopes : pour debuter en lecture-seule (recommande), coche :

crm.objects.contacts.read
crm.objects.companies.read
crm.objects.deals.read
crm.schemas.contacts.read + companies/deals (schemas)

Tu pourras ajouter .write et crm.objects.tickets.read, crm.objects.engagements.read plus tard quand tu seras a l'aise.

Clique Create app. Copie le token d'acces qui s'affiche. Tu ne le reverras pas une fois la page fermee.

Securite : ce token donne acces a ton CRM. Ne le commit jamais dans Git, ne le partage pas. Stocke-le dans un password manager. Revoque-le immediatement si compromis (Private apps » Manage).

Configurer Claude Desktop

Localise le fichier de config Claude Desktop selon ton OS :

Mac : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Ouvre le fichier dans ton editeur (s'il n'existe pas, cree-le) et ajoute :

{
  "mcpServers": {
    "hubspot": {
      "url": "https://mcp.hubspot.com/v1/{YOUR_PORTAL_ID}",
      "headers": {
        "Authorization": "Bearer {YOUR_PRIVATE_APP_TOKEN}"
      }
    }
  }
}

Remplace {YOUR_PORTAL_ID} par l'ID de l'etape 1 et {YOUR_PRIVATE_APP_TOKEN} par le token de l'etape 2.

Sauvegarde le fichier puis quitte completement Claude Desktop (Cmd+Q sur Mac, pas juste fermer la fenetre) et relance-le.

Premiere connexion et verification

Au premier lancement apres modification du config, Claude Desktop affiche une icone d'outil (cle a molette) dans le coin inferieur droit de la zone de chat. Clique dessus.

Tu dois voir hubspot dans la liste des MCP servers connectes. Si oui : c'est gagne. Si non : voir le troubleshooting plus bas.

Pour tester rapidement, demande a Claude :

Donne-moi les 5 derniers contacts crees dans HubSpot,
avec leur email, leur entreprise et leur date de creation.

Claude va t'afficher un prompt de confirmation « HubSpot wants to query your contacts ». Accepte. Tu vois le resultat reel de ton CRM dans la conversation. Premier « wow moment ».

5 premiers prompts utiles RevOps

Voici 5 prompts qui marchent bien des le J1 et te montreront la puissance reelle :

1. Pipeline coverage du Q en cours

Quels deals dans le pipeline (stage != Closed Won/Lost)
ont une close_date dans le Q en cours ? Total, par owner,
par stage. Calcule le coverage vs un objectif de 1M EUR.

2. Deals fantomes

Liste les deals ouverts sans activite (engagement) depuis 14 jours.
Format : Nom du deal, owner, montant, derniere activite, age.
Sort par montant decroissant.

3. Brief avant un meeting

Brief contextuel sur le contact pierre.dupont@example.com :
historique deals, derniers emails recus/envoyes, notes,
et company info. 200 mots max, format puces.

4. Qualite data

Combien de contacts ont un email sans nom, ou un nom sans email,
ou pas d'industry renseigne ? Donne le top 10 des problemes
de qualite data sur les contacts crees ces 30 derniers jours.

5. Comparatif segments

Compare les deals fermes won des 90 derniers jours vs ceux
fermes lost : taille company moyenne, cycle de vente,
nombre d'engagements, source. Trouve les 3 patterns gagnants.

Troubleshooting : les 4 problemes classiques

Claude ne voit pas le serveur HubSpot

Verifie que tu as bien quitte completement Claude Desktop (Cmd+Q / Alt+F4) avant relance. Verifie le JSON du config file avec un linter (jsonlint.com) pour t'assurer qu'il est valide.

Erreur 401 Unauthorized

Le token est invalide ou expire. Regenere une private app dans HubSpot et remplace le token dans le config.

Erreur 403 Forbidden

Le scope demande n'est pas dans ta private app. Verifie les scopes coches a l'etape 2 et ajoute ceux dont tu as besoin.

Rate limit (429)

Le MCP server applique les rate limits HubSpot API v3 (100 req/10s). Si tu itererais sur 1000 contacts, batch-les via des queries plus larges (filters) plutot que en boucle.

Besoin d'aide pour deployer MCP en prod ?

30 min avec Guillaume pour cadrer ton deploiement MCP : scopes, securite, gouvernance, premiers cas d'usage.

Reserver un creneau

Continuer la lecture

IA & Automatisation

Tutoriel HubSpot MCP server : setup en 30 minutes