HubSpot MCP Server

Interaja com a API do HubSpot CRM para análise e insights de vendas.

Documentação

Servidor MCP HubSpot

Servidor MCP para a API do HubSpot, permitindo que o Claude interaja com o CRM do HubSpot para análise de vendas e insights.

Aviso

Este projeto de código aberto não é afiliado ou endossado pela HubSpot. É uma implementação independente que interage com a API da HubSpot.

Ferramentas

Ferramentas Principais de CRM

hubspot_search_contacts
- Pesquisar contatos no HubSpot usando uma string de consulta
- Entradas obrigatórias:
  - query (string): String de consulta de pesquisa (email, nome, etc.)
- Entradas opcionais:
  - count (número, padrão: 10): Número máximo de contatos a retornar
  - propertyList (array): Lista de propriedades a incluir nos resultados
- Retorna: Lista de contatos correspondentes com suas propriedades
hubspot_get_contact
- Obter um contato específico por ID
- Entradas obrigatórias:
  - contactId (string): O ID do contato a recuperar
- Entradas opcionais:
  - properties (array): Lista de propriedades a incluir nos resultados
- Retorna: Detalhes do contato com as propriedades especificadas
hubspot_create_contact
- Criar um novo contato no HubSpot
- Entradas obrigatórias:
  - properties (objeto): Propriedades do contato com pelo menos o campo email
- Retorna: Detalhes do contato criado
hubspot_update_contact
- Atualizar um contato existente no HubSpot
- Entradas obrigatórias:
  - contactId (string): O ID do contato a atualizar
  - properties (objeto): Propriedades do contato a atualizar
- Retorna: Confirmação do contato atualizado
hubspot_list_deals
- Listar negócios no HubSpot com paginação
- Entradas opcionais:
  - limit (número, padrão: 10, máximo: 100): Número máximo de negócios a retornar
  - after (string): Cursor de paginação para a próxima página
  - properties (array): Lista de propriedades a incluir nos resultados
- Retorna: Lista de negócios com seus detalhes
hubspot_get_deal
- Obter um negócio específico por ID
- Entradas obrigatórias:
  - dealId (string): O ID do negócio a recuperar
- Entradas opcionais:
  - properties (array): Lista de propriedades a incluir nos resultados
- Retorna: Detalhes do negócio com as propriedades especificadas
hubspot_create_deal
- Criar um novo negócio no HubSpot
- Entradas obrigatórias:
  - properties (objeto): Propriedades do negócio com pelo menos o campo dealname
- Retorna: Detalhes do negócio criado
hubspot_update_deal
- Atualizar um negócio existente no HubSpot
- Entradas obrigatórias:
  - dealId (string): O ID do negócio a atualizar
  - properties (objeto): Propriedades do negócio a atualizar
- Retorna: Confirmação do negócio atualizado
hubspot_list_companies
- Listar empresas no HubSpot com paginação
- Entradas opcionais:
  - limit (número, padrão: 10, máximo: 100): Número máximo de empresas a retornar
  - after (string): Cursor de paginação para a próxima página
  - properties (array): Lista de propriedades a incluir nos resultados
- Retorna: Lista de empresas com seus detalhes
hubspot_get_company
- Obter uma empresa específica por ID
- Entradas obrigatórias:
  - companyId (string): O ID da empresa a recuperar
- Entradas opcionais:
  - properties (array): Lista de propriedades a incluir nos resultados
- Retorna: Detalhes da empresa com as propriedades especificadas

Ferramentas de Análise de Vendas

hubspot_get_sales_analytics
- Obter dados analíticos de vendas agregados para períodos de tempo específicos
- Entradas obrigatórias:
  - period (string): Período de tempo para agrupar os dados analíticos (diário, semanal, mensal, trimestral, anual)
  - startDate (string): Data de início para análise no formato ISO (AAAA-MM-DD)
- Entradas opcionais:
  - endDate (string): Data de término para análise no formato ISO
  - pipeline (string): ID do pipeline para filtrar
  - dealStage (string): ID da etapa do negócio para filtrar
  - dealOwner (string): ID do proprietário do negócio para filtrar
- Retorna: Métricas de vendas agregadas agrupadas por período de tempo
hubspot_get_deal_history
- Obter o histórico completo de alterações de um negócio
- Entradas obrigatórias:
  - dealId (string): O ID do negócio para obter o histórico
- Retorna: Histórico de alterações do negócio com carimbos de data/hora e propriedades modificadas
hubspot_get_deal_notes
- Obter notas associadas a um negócio específico
- Entradas obrigatórias:
  - dealId (string): O ID do negócio para obter as notas
- Entradas opcionais:
  - limit (número, padrão: 20): Número máximo de notas a retornar
  - after (string): Cursor de paginação para a próxima página de resultados
- Retorna: Lista de notas com seu conteúdo e carimbos de data/hora de criação
hubspot_get_engagements_by_deal
- Obter todas as atividades de engajamento associadas a um negócio
- Entradas obrigatórias:
  - dealId (string): O ID do negócio para obter os engajamentos
- Entradas opcionais:
  - types (array): Tipos de engajamentos a incluir (CHAMADA, EMAIL, REUNIÃO, TAREFA, NOTA)
  - limit (número, padrão: 20): Número máximo de engajamentos a retornar
  - after (string): Cursor de paginação para a próxima página de resultados
- Retorna: Lista de engajamentos com seus detalhes e informações de tipo
hubspot_get_sales_performance
- Obter métricas de desempenho para representantes de vendas em um período de tempo específico
- Entradas obrigatórias:
  - period (string): Período de tempo para agrupar os dados de desempenho (diário, semanal, mensal, trimestral, anual)
  - startDate (string): Data de início para análise no formato ISO (AAAA-MM-DD)
- Entradas opcionais:
  - endDate (string): Data de término para análise no formato ISO
  - ownerIds (array): Lista de IDs de proprietários a incluir na análise
  - pipeline (string): ID do pipeline para filtrar
- Retorna: Métricas de desempenho para cada representante de vendas, incluindo contagens de negócios, receita e taxas de vitória
hubspot_get_pipeline_analytics
- Obter análises para um pipeline de vendas específico, incluindo taxas de conversão entre etapas
- Entradas obrigatórias:
  - pipelineId (string): O ID do pipeline a analisar
  - period (string): Período de tempo para agrupar os dados analíticos (diário, semanal, mensal, trimestral, anual)
  - startDate (string): Data de início para análise no formato ISO (AAAA-MM-DD)
- Entradas opcionais:
  - endDate (string): Data de término para análise no formato ISO
- Retorna: Métricas de etapas do pipeline, incluindo contagens de negócios, valores, taxas de conversão e tempo na etapa
hubspot_get_forecast_analytics
- Obter dados de vendas previstos com base no pipeline atual e no desempenho histórico
- Entradas obrigatórias:
  - period (string): Período de tempo para agrupar os dados de previsão (mensal, trimestral, anual)
- Entradas opcionais:
  - numberOfPeriods (número, padrão: 3): Número de períodos futuros a prever
  - pipeline (string): ID do pipeline para filtrar
- Retorna: Métricas de vendas previstas para períodos futuros com base em dados históricos e no pipeline atual

Configuração

Criar um aplicativo privado do HubSpot:
- Acesse sua conta do HubSpot
- Navegue até Configurações → Configuração da conta → Integrações → Aplicativos privados
- Clique em "Criar aplicativo privado"
- Dê um nome ao seu aplicativo e defina os escopos apropriados (contatos, negócios e empresas)
- Crie o aplicativo e copie o token do seu aplicativo privado
Escopos necessários:
- 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 com o Claude Desktop

Adicione o seguinte ao seu 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"
      }
    }
  }
}

Solução de problemas

Se você encontrar erros, verifique se:

Todos os escopos necessários foram adicionados ao seu aplicativo privado do HubSpot
A chave da API foi copiada corretamente para a sua configuração
Seu plano do HubSpot inclui acesso às APIs que você está tentando usar

Build

Build do Docker:

docker build -t mcp/hubspot -f Dockerfile .

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.