HubSpot MCP

Uma implementação de servidor Model Context Protocol (MCP) para a API do HubSpot, fornecendo uma interface padronizada para acessar e gerenciar dados de CRM.

Recursos

• Cobertura completa da API de CRM do HubSpot
• Suporte para todos os objetos padrão de CRM (empresas, contatos, negócios, etc.)
• Gerenciamento avançado de associações com CRM Associations v4
• Endpoints específicos de empresas com validação de propriedades
• Operações em lote para gerenciamento eficiente de dados
• Recursos avançados de pesquisa e filtragem
• Validação de parâmetros type-safe com Zod

Pré-requisitos

Se você não tiver uma chave de API, siga os passos aqui para obter um token de acesso. O suporte a OAuth está planejado como uma melhoria futura.

Configuração do Cliente

Existem várias opções para configurar seu cliente MCP com o servidor. Para configuração de servidor hospedado/remoto, use a CLI do Smithery com uma Smithery API Key. Para instalação local, use npx ou compile a partir do código-fonte. Cada uma dessas opções é explicada abaixo.

Smithery Remote Server (Recomendado)

Para adicionar um servidor remoto ao seu cliente MCP config.json, execute o seguinte comando a partir da Smithery CLI:

npx -y @smithery/cli install @shinzo-labs/hubspot-mcp

Digite seu HUBSPOT_ACCESS_TOKEN quando solicitado.

Smithery SDK

Se você está desenvolvendo sua própria aplicação de agente, pode usar o código boilerplate aqui.

Instalação Local via NPX

Para instalar o servidor localmente com npx, adicione o seguinte ao seu cliente MCP config.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "@shinzolabs/hubspot-mcp"
      ],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Compilar a partir do Código-Fonte

1. Baixe o repositório:

git clone https://github.com/shinzo-labs/hubspot-mcp.git

2. Instale os pacotes (dentro do repositório clonado):

pnpm i

3. Adicione o seguinte ao seu cliente MCP config.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": [
        "/path/to/hubspot-mcp/index.js"
      ],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Variáveis de Configuração

Variável	Descrição	Obrigatória?	Padrão
HUBSPOT_ACCESS_TOKEN	Token de acesso para o aplicativo HubSpot	Sim
PORT	Porta para o método de transporte HTTP Streamable	Não	3000
TELEMETRY_ENABLED	Habilitar telemetria	Não	true

Ferramentas Suportadas

Objetos Principais de CRM

• crm_list_objects: Listar objetos de CRM com filtragem e paginação opcionais
• crm_get_object: Obter um único objeto de CRM por ID
• crm_create_object: Criar um novo objeto de CRM
• crm_update_object: Atualizar um objeto de CRM existente
• crm_archive_object: Arquivar (excluir) um objeto de CRM
• crm_search_objects: Pesquisar objetos de CRM usando filtros avançados
• crm_batch_create_objects: Criar vários objetos em uma única solicitação
• crm_batch_read_objects: Ler vários objetos em uma única solicitação
• crm_batch_update_objects: Atualizar vários objetos em uma única solicitação
• crm_batch_archive_objects: Arquivar (excluir) vários objetos em uma única solicitação

Empresas

• crm_create_company: Criar uma nova empresa com propriedades validadas
• crm_update_company: Atualizar uma empresa existente
• crm_get_company: Obter uma única empresa por ID
• crm_search_companies: Pesquisar empresas com filtros específicos
• crm_batch_create_companies: Criar várias empresas em uma única solicitação
• crm_batch_update_companies: Atualizar várias empresas em uma única solicitação
• crm_get_company_properties: Obter todas as propriedades de empresa disponíveis
• crm_create_company_property: Criar uma nova propriedade de empresa

Contatos

• crm_create_contact: Criar um novo contato com propriedades validadas
• crm_update_contact: Atualizar as informações de um contato existente
• crm_get_contact: Obter um único contato por ID
• crm_search_contacts: Pesquisar contatos com filtros específicos
• crm_batch_create_contacts: Criar vários contatos em uma única solicitação
• crm_batch_update_contacts: Atualizar vários contatos em uma única solicitação
• crm_get_contact_properties: Obter todas as propriedades de contato disponíveis
• crm_create_contact_property: Criar uma nova propriedade de contato

Leads

• crm_create_lead: Criar um novo lead com propriedades validadas
• crm_update_lead: Atualizar as informações de um lead existente
• crm_get_lead: Obter um único lead por ID
• crm_search_leads: Pesquisar leads com filtros específicos
• crm_batch_create_leads: Criar vários leads em uma única solicitação
• crm_batch_update_leads: Atualizar vários leads em uma única solicitação
• crm_get_lead_properties: Obter todas as propriedades de lead disponíveis
• crm_create_lead_property: Criar uma nova propriedade de lead

Gerenciamento de Engajamentos

• engagement_details_get: Obter detalhes de um engajamento específico
• engagement_details_create: Criar um novo engajamento
• engagement_details_update: Atualizar um engajamento existente
• engagement_details_archive: Arquivar (excluir) um engajamento
• engagement_details_list: Listar todos os engajamentos com filtragem
• engagement_details_get_associated: Obter engajamentos associados

Chamadas

• calls_create: Criar um novo registro de chamada
• calls_get: Obter detalhes da chamada
• calls_update: Atualizar um registro de chamada
• calls_archive: Arquivar uma chamada
• calls_list: Listar todas as chamadas
• calls_search: Pesquisar chamadas
• calls_batch_create: Criar várias chamadas
• calls_batch_read: Ler várias chamadas
• calls_batch_update: Atualizar várias chamadas
• calls_batch_archive: Arquivar várias chamadas

E-mails

• emails_create: Criar um novo registro de e-mail
• emails_get: Obter detalhes do e-mail
• emails_update: Atualizar um e-mail
• emails_archive: Arquivar um e-mail
• emails_list: Listar todos os e-mails
• emails_search: Pesquisar e-mails
• emails_batch_create: Criar vários e-mails
• emails_batch_read: Ler vários e-mails
• emails_batch_update: Atualizar vários e-mails
• emails_batch_archive: Arquivar vários e-mails

Reuniões

• meetings_create: Criar uma nova reunião
• meetings_get: Obter detalhes da reunião
• meetings_update: Atualizar uma reunião
• meetings_archive: Arquivar (excluir) uma reunião
• meetings_list: Listar todas as reuniões
• meetings_search: Pesquisar reuniões
• meetings_batch_create: Criar várias reuniões
• meetings_batch_update: Atualizar várias reuniões
• meetings_batch_archive: Arquivar várias reuniões

Notas

• notes_create: Criar uma nova nota
• notes_get: Obter detalhes da nota
• notes_update: Atualizar uma nota
• notes_archive: Arquivar uma nota
• notes_list: Listar todas as notas
• notes_search: Pesquisar notas
• notes_batch_create: Criar várias notas
• notes_batch_read: Ler várias notas
• notes_batch_update: Atualizar várias notas
• notes_batch_archive: Arquivar várias notas

Tarefas

• tasks_create: Criar uma nova tarefa
• tasks_get: Obter detalhes da tarefa
• tasks_update: Atualizar uma tarefa
• tasks_archive: Arquivar uma tarefa
• tasks_list: Listar todas as tarefas
• tasks_search: Pesquisar tarefas
• tasks_batch_create: Criar várias tarefas
• tasks_batch_read: Ler várias tarefas
• tasks_batch_update: Atualizar várias tarefas
• tasks_batch_archive: Arquivar várias tarefas

Associações e Relacionamentos

• crm_list_association_types: Listar tipos de associação disponíveis
• crm_get_associations: Obter todas as associações entre objetos
• crm_create_association: Criar uma associação
• crm_archive_association: Arquivar (excluir) uma associação
• crm_batch_create_associations: Criar várias associações
• crm_batch_archive_associations: Arquivar (excluir) várias associações

Preferências de Comunicação

• communications_get_preferences: Obter preferências de contato
• communications_update_preferences: Atualizar preferências de contato
• communications_unsubscribe_contact: Cancelar inscrição global
• communications_subscribe_contact: Inscrever-se globalmente
• communications_get_subscription_definitions: Obter definições de assinatura
• communications_get_subscription_status: Obter status de vários contatos
• communications_update_subscription_status: Atualizar status de vários contatos

Produtos

• products_create: Criar um produto com as propriedades fornecidas e retornar uma cópia do objeto, incluindo o ID.
• products_read: Ler um objeto identificado por ID
• products_update: Realizar uma atualização parcial de um objeto identificado por ID. Propriedades somente leitura e inexistentes resultarão em erro. Os valores das propriedades podem ser limpos passando uma string vazia.
• products_archive: Mover um objeto identificado por ID para a lixeira.
• products_list: Ler uma página de produtos. Controle o que é retornado por meio do parâmetro de consulta properties. after é o token de cursor de paginação do último recurso lido com sucesso, que será retornado como a propriedade JSON paging.next.after de uma resposta paginada contendo mais resultados.
• products_search: Pesquisar produtos
• products_batch_create: Criar um lote de produtos
• products_batch_read: Ler um lote de produtos por ID interno ou valores de propriedade exclusivos. Recupere registros pelo parâmetro idProperty para recuperar registros por uma propriedade de valor exclusivo personalizada.
• products_batch_update: Atualizar um lote de produtos por ID interno ou valores exclusivos especificados pelo parâmetro de consulta idProperty.
• products_batch_archive: Arquivar um lote de produtos por ID

Contribuindo

Contribuições são bem-vindas e incentivadas! Leia CONTRIBUTING.md para obter diretrizes sobre problemas, contribuições e informações de contato.

Coleta de Dados e Privacidade

A Shinzo Labs coleta telemetria anônima limitada deste servidor para ajudar a melhorar nossos produtos e serviços. Nenhuma informação pessoalmente identificável é coletada como parte desse processo. Revise a Política de Privacidade para obter mais detalhes sobre os tipos de dados coletados e como optar por não participar dessa telemetria.

Licença

MIT