Ops HubSpot CRM Server

Serveur MCP (Model Context Protocol) personnalisé pour HubSpot CRM — segmentation ICP, scoring, détection de doublons, Data Quality Score et automatisation lifecycle stage.

Structure

hubspot-mcp-server/
├── server.py           # Serveur MCP FastMCP (39 outils)
├── requirements.txt    # Dépendances Python
├── .env.example        # Template de configuration
└── .gitignore

Rôle

Expose la logique métier propre au workspace (Fit Score ICP, détection doublons, calcul DQS) que le MCP officiel HubSpot ne fournit pas nativement.

Installation

cd hubspot-mcp-server
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Éditer .env avec ton Private App Access Token HubSpot

Démarrage

python server.py
# Tester avec MCP Inspector : npx @modelcontextprotocol/inspector python server.py

Outils exposés (39)

Audit & Qualité

• audit_contacts_completeness — calcule le taux de complétude
• compute_dqs — calcul du Data Quality Score (DQS)
• detect_duplicate_contacts — détection de doublons (name+company, email)
• detect_duplicate_companies — détection de doublons companies

Scoring & Segmentation

• calculate_fit_score — applique la grille ICP Fit Score
• calculate_company_fit_score — scoring firmographique companies
• calculate_company_engagement_score — scoring engagement companies
• calculate_company_combined_score — score combiné (fit + engagement + techno)
• calculate_company_techno_score — scoring technographique
• sync_segmentation_properties — synchronise les propriétés ICP
• sync_company_segmentation — segmentation companies

Lifecycle & Pipeline

• update_lifecyclestage — promotion automatique de lifecyclestage
• update_company_lifecyclestage — lifecyclestage companies
• detect_founder_signals — détection des signaux forts founder-led
• detect_company_signals — détection signaux companies

Enrichissement & Complétion

• standardize_contact — standardisation des contacts
• standardize_company_properties — standardisation companies
• complete_missing_fields — complétion champs critiques
• complete_company_fields — complétion companies

Reporting

• generate_weekly_report — rapport hebdomadaire complet
• generate_company_report — rapport companies
• generate_revops_report — rapport RevOps

Administration

• create_custom_properties — création des propriétés custom
• fix_lifecycle_stages — correction lifecycle stages
• dedupe_contacts — fusion de doublons contacts
• dedupe_companies — fusion de doublons companies
• bulk_update_properties — mise à jour en masse

Propriétés Custom

Contacts (6)

Propriété	Type	Description
fit_score	number	Score ICP 0-50
icp_tier	dropdown	Tier 1 / Tier 2 / Tier 3 / Not ICP
founder_signal_type	string	Type de signal founder détecté
last_signal_date	date	Date du dernier signal
duplicate_flag	boolean	Contact potentiellement dupliqué
tier1_alert_sent_date	date	Date d'alerte Tier 1

Companies (11)

Propriété	Type	Description
icp_tier_company	dropdown	Tier 1 / Tier 2 / Tier 3
company_fit_score	number	Score fit 0-60
company_engagement_score	number	Score engagement 0-40
company_combined_score	number	Score combiné 0-118
company_techno_score	number	Score techno 0-18
last_company_sync_date	date	Dernière synchronisation
company_tier1_alert_sent_date	date	Date d'alerte Tier 1
recent_funding_amount	number	Financement récent
num_locations	number	Nombre de localisations
existing_hubspot_customer	boolean	Client HubSpot existant
ecommerce_stack	string	Stack e-commerce

Bug Fixes (2026-07-16)

39 bugs identifiés et corrigés le 2026-07-16 :

• BUG-01 : hs_ prefix sur propriétés custom → renommé en recent_funding_amount
• BUG-02 : Options vides sur boolean → ajout options true/false
• BUG-03 : Lifecyclestage regression → forward-only enforcement
• BUG-04 : HubSpot search limit 200 → pagination automatique
• BUG-05 : Contact standardization modifie champs protégés → exclusion email/firstname/lastname/company/lifecyclestage/hs_lead_status
• BUG-06 : Company name auto-write → flagged to review queue
• BUG-07 : Phone field auto-write → jamais écrit automatiquement
• BUG-08 : Duplicate merge sans validation → human confirmation required
• BUG-09 : Irreversible actions sans confirmation → dry_run par défaut
• BUG-10 : Dropdown options mismatch → labels exacts server.py
• BUG-11 : DQS formula incorrect → (completeness×0.40) + ((1-doublons)×0.20) + (segmentation×0.20) + (pipeline_activity×0.20)
• BUG-12 : ICP weight auto-apply → human validation required
• BUG-13 : Breeze Intelligence API trigger → détection gaps uniquement
• BUG-14 : Config paths wrong → ~/nanobot-workspace/ par défaut
• BUG-15 : Sales Hub Starter constraint → custom icp_tier_company dropdown

Configuration

Créer un fichier .env à la racine avec :

HUBSPOT_ACCESS_TOKEN=pat-xxxxxxxxxxxx

Ou utiliser ~/nanobot_secrets.env (chmod 600) sourcé via .bashrc.

License

Private — usage interne uniquement.