HubSpot MCP Server

Servidor MCP de HubSpot

Servidor MCP para la API de HubSpot, que permite a Claude interactuar con el CRM de HubSpot para análisis de ventas e información.

Aviso legal

Este proyecto de código abierto no está afiliado ni respaldado por HubSpot. Es una implementación independiente que interactúa con la API de HubSpot.

Herramientas

Herramientas principales de CRM

1. hubspot_search_contacts

   • Buscar contactos en HubSpot usando una cadena de consulta
   • Entradas requeridas:
     • query (cadena): Cadena de consulta de búsqueda (correo electrónico, nombre, etc.)
   • Entradas opcionales:
     • count (número, predeterminado: 10): Número máximo de contactos a devolver
     • propertyList (matriz): Lista de propiedades a incluir en los resultados
   • Devuelve: Lista de contactos coincidentes con sus propiedades

2. hubspot_get_contact

   • Obtener un contacto específico por ID
   • Entradas requeridas:
     • contactId (cadena): El ID del contacto a recuperar
   • Entradas opcionales:
     • properties (matriz): Lista de propiedades a incluir en los resultados
   • Devuelve: Detalles del contacto con las propiedades especificadas

3. hubspot_create_contact

   • Crear un nuevo contacto en HubSpot
   • Entradas requeridas:
     • properties (objeto): Propiedades del contacto con al menos el campo email
   • Devuelve: Detalles del contacto creado

4. hubspot_update_contact

   • Actualizar un contacto existente en HubSpot
   • Entradas requeridas:
     • contactId (cadena): El ID del contacto a actualizar
     • properties (objeto): Propiedades del contacto a actualizar
   • Devuelve: Confirmación del contacto actualizado

5. hubspot_list_deals

   • Listar negocios en HubSpot con paginación
   • Entradas opcionales:
     • limit (número, predeterminado: 10, máximo: 100): Número máximo de negocios a devolver
     • after (cadena): Cursor de paginación para la siguiente página
     • properties (matriz): Lista de propiedades a incluir en los resultados
   • Devuelve: Lista de negocios con sus detalles

6. hubspot_get_deal

   • Obtener un negocio específico por ID
   • Entradas requeridas:
     • dealId (cadena): El ID del negocio a recuperar
   • Entradas opcionales:
     • properties (matriz): Lista de propiedades a incluir en los resultados
   • Devuelve: Detalles del negocio con las propiedades especificadas

7. hubspot_create_deal

   • Crear un nuevo negocio en HubSpot
   • Entradas requeridas:
     • properties (objeto): Propiedades del negocio con al menos el campo dealname
   • Devuelve: Detalles del negocio creado

8. hubspot_update_deal

   • Actualizar un negocio existente en HubSpot
   • Entradas requeridas:
     • dealId (cadena): El ID del negocio a actualizar
     • properties (objeto): Propiedades del negocio a actualizar
   • Devuelve: Confirmación del negocio actualizado

9. hubspot_list_companies

   • Listar empresas en HubSpot con paginación
   • Entradas opcionales:
     • limit (número, predeterminado: 10, máximo: 100): Número máximo de empresas a devolver
     • after (cadena): Cursor de paginación para la siguiente página
     • properties (matriz): Lista de propiedades a incluir en los resultados
   • Devuelve: Lista de empresas con sus detalles

10. hubspot_get_company

    • Obtener una empresa específica por ID
    • Entradas requeridas:
      • companyId (cadena): El ID de la empresa a recuperar
    • Entradas opcionales:
      • properties (matriz): Lista de propiedades a incluir en los resultados
    • Devuelve: Detalles de la empresa con las propiedades especificadas

Herramientas de análisis de ventas

11. hubspot_get_sales_analytics

    • Obtener datos agregados de análisis de ventas para períodos de tiempo específicos
    • Entradas requeridas:
      • period (cadena): Período de tiempo para agrupar los datos de análisis (diario, semanal, mensual, trimestral, anual)
      • startDate (cadena): Fecha de inicio para el análisis en formato ISO (AAAA-MM-DD)
    • Entradas opcionales:
      • endDate (cadena): Fecha de fin para el análisis en formato ISO
      • pipeline (cadena): ID del pipeline para filtrar
      • dealStage (cadena): ID de la etapa del negocio para filtrar
      • dealOwner (cadena): ID del propietario del negocio para filtrar
    • Devuelve: Métricas de ventas agregadas agrupadas por período de tiempo

12. hubspot_get_deal_history

    • Obtener el historial completo de cambios de un negocio
    • Entradas requeridas:
      • dealId (cadena): El ID del negocio del cual obtener el historial
    • Devuelve: Historial de cambios del negocio con marcas de tiempo y propiedades modificadas

13. hubspot_get_deal_notes

    • Obtener notas asociadas con un negocio específico
    • Entradas requeridas:
      • dealId (cadena): El ID del negocio del cual obtener las notas
    • Entradas opcionales:
      • limit (número, predeterminado: 20): Número máximo de notas a devolver
      • after (cadena): Cursor de paginación para la siguiente página de resultados
    • Devuelve: Lista de notas con su contenido y marcas de tiempo de creación

14. hubspot_get_engagements_by_deal

    • Obtener todas las actividades de interacción asociadas con un negocio
    • Entradas requeridas:
      • dealId (cadena): El ID del negocio del cual obtener las interacciones
    • Entradas opcionales:
      • types (matriz): Tipos de interacciones a incluir (LLAMADA, CORREO, REUNIÓN, TAREA, NOTA)
      • limit (número, predeterminado: 20): Número máximo de interacciones a devolver
      • after (cadena): Cursor de paginación para la siguiente página de resultados
    • Devuelve: Lista de interacciones con sus detalles e información de tipo

15. hubspot_get_sales_performance

    • Obtener métricas de rendimiento para representantes de ventas durante un período de tiempo específico
    • Entradas requeridas:
      • period (cadena): Período de tiempo para agrupar los datos de rendimiento (diario, semanal, mensual, trimestral, anual)
      • startDate (cadena): Fecha de inicio para el análisis en formato ISO (AAAA-MM-DD)
    • Entradas opcionales:
      • endDate (cadena): Fecha de fin para el análisis en formato ISO
      • ownerIds (matriz): Lista de IDs de propietarios a incluir en el análisis
      • pipeline (cadena): ID del pipeline para filtrar
    • Devuelve: Métricas de rendimiento para cada representante de ventas, incluyendo conteos de negocios, ingresos y tasas de éxito

16. hubspot_get_pipeline_analytics

    • Obtener análisis para un pipeline de ventas específico, incluyendo tasas de conversión entre etapas
    • Entradas requeridas:
      • pipelineId (cadena): El ID del pipeline a analizar
      • period (cadena): Período de tiempo para agrupar los datos de análisis (diario, semanal, mensual, trimestral, anual)
      • startDate (cadena): Fecha de inicio para el análisis en formato ISO (AAAA-MM-DD)
    • Entradas opcionales:
      • endDate (cadena): Fecha de fin para el análisis en formato ISO
    • Devuelve: Métricas de etapas del pipeline, incluyendo conteos de negocios, valores, tasas de conversión y tiempo en etapa

17. hubspot_get_forecast_analytics

    • Obtener datos de pronóstico de ventas basados en el pipeline actual y el rendimiento histórico
    • Entradas requeridas:
      • period (cadena): Período de tiempo para agrupar los datos de pronóstico (mensual, trimestral, anual)
    • Entradas opcionales:
      • numberOfPeriods (número, predeterminado: 3): Número de períodos futuros a pronosticar
      • pipeline (cadena): ID del pipeline para filtrar
    • Devuelve: Métricas de ventas pronosticadas para períodos futuros basadas en datos históricos y el pipeline actual

Configuración

1. Crear una aplicación privada de HubSpot:

   • Vaya a su cuenta de HubSpot
   • Navegue a Configuración → Configuración de la cuenta → Integraciones → Aplicaciones privadas
   • Haga clic en "Crear aplicación privada"
   • Asigne un nombre a su aplicación y establezca los alcances apropiados (contactos, negocios y empresas)
   • Cree la aplicación y copie su token de aplicación privada

2. Alcances requeridos:

   • crm.objects.contacts.read
   • crm.objects.contacts.write
   • crm.objects.deals.read
   • crm.objects.deals.write
   • crm.objects.companies.read
   • crm.objects.companies.write
   • crm.objects.owners.read
   • crm.objects.quotes.read
   • crm.objects.line_items.read
   • crm.objects.custom.read
   • crm.schemas.deals.read
   • crm.schemas.contacts.read
   • crm.schemas.companies.read
   • crm.schemas.custom.read

Uso con Claude Desktop

Agregue lo siguiente a su claude_desktop_config.json:

npx

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

docker

{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HUBSPOT_API_KEY", "mcp/hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Solución de problemas

Si encuentra errores, verifique que:

1. Todos los alcances requeridos estén agregados a su aplicación privada de HubSpot
2. La clave de API esté copiada correctamente en su configuración
3. Su plan de HubSpot incluya acceso a las API que está intentando usar

Compilación

Compilación de Docker:

docker build -t mcp/hubspot -f Dockerfile .

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que es libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulte el archivo LICENSE en el repositorio del proyecto.