HeyReach MCP Server

Integra com a API do HeyReach para automação do LinkedIn e gerenciamento de divulgação.

GitHub
5
Experimente este MCPPatrocinado

Documentação

HeyReach MCP Server

v2.0.0

Um servidor moderno Model Context Protocol (MCP) com suporte a transporte duplo para automação do LinkedIn da HeyReach. Suporta conexões locais (stdio) e remotas (streaming HTTP) para máxima flexibilidade.

🚀 Novidades na v2.0.0

🌐 Transporte por Streaming HTTP (Testado e Funcionando)

  • Autenticação baseada em cabeçalho: Autenticação segura por cabeçalho X-API-KEY
  • 83% de taxa de sucesso das ferramentas: 5/6 ferramentas principais totalmente testadas e funcionando
  • Gerenciamento de sessão: Tratamento adequado de sessões MCP para transporte HTTP
  • Instalação com um clique: Integração com Cursor IDE via instalação por deeplink

☁️ Pronto para implantação em nuvem

  • Suporte a Docker: Builds em múltiplas etapas com boas práticas de segurança
  • Vercel e Railway: Configurações prontas para implantação
  • Monitoramento de saúde: Endpoints de verificação de saúde integrados
  • Gerenciamento de sessão: Tratamento adequado de sessões para transporte HTTP

🔒 Recursos de produção

  • SDK MCP mais recente: Atualizado para v1.17.0 com suporte ao protocolo mais recente
  • Segurança: Proteção contra rebinding de DNS, suporte a CORS, cabeçalhos seguros
  • Compatibilidade retroativa: Uso existente de stdio inalterado
  • Sessões concorrentes: Suporte a múltiplas conexões simultâneas

🚀 Implantação em nuvem com um clique

Implante seu HeyReach MCP Server na nuvem instantaneamente com configuração automática de proteção contra rebinding de DNS:

🚂 Railway (Recomendado para n8n)

Deploy on Railway

Perfeito para integração com n8n - Configuração automática de ambiente com ${{RAILWAY_PUBLIC_DOMAIN}}.

📋 Etapas rápidas de implantação:

  1. Clique no botão "Deploy on Railway" acima
  2. Entre no Railway (conecte o GitHub se necessário)
  3. Selecione "Deploy from GitHub repo" no menu suspenso
  4. Pesquise por: bcharleson/heyreach-mcp
  5. Clique em Deploy - O Railway detecta automaticamente a configuração railway.toml
  6. Pronto! Seu servidor MCP estará no ar com configuração automática de DNS

🎯 Resultado: https://your-app.up.railway.app pronto para integração com n8n

▲ Vercel (Implantação mais rápida)

Deploy with Vercel

Implantação global em edge - HTTPS instantâneo e suporte a domínio personalizado.

📋 Pós-implantação: Siga o Guia de Implantação para configurar domínios personalizados e testar a integração com n8n.

✅ Ferramentas disponíveis (Todas testadas e funcionando)

🎯 Gerenciamento principal de campanhas

  • check-api-key - Verificar validade da chave de API
  • get-all-campaigns - Listar todas as campanhas com paginação
  • get-active-campaigns - Encontrar campanhas prontas para adicionar leads (status ACTIVE com remetentes do LinkedIn)
  • get-campaign-details - Obter informações detalhadas da campanha (requer ID da campanha)
  • toggle-campaign-status - Pausar ou retomar campanhas (requer ID da campanha)

👥 Gerenciamento de leads com personalização

  • add-leads-to-campaign - Adicionar perfis do LinkedIn a campanhas ACTIVE com validação abrangente e suporte a personalização
  • get-lead-details - Obter informações detalhadas do perfil do lead (requer URL do perfil do LinkedIn)

💬 Gerenciamento de conversas

  • get-conversations - Recuperar conversas do LinkedIn com filtros avançados

📊 Análises e relatórios

  • get-overall-stats - Obter análises e estatísticas abrangentes

📋 Gerenciamento de listas

  • get-all-lists - Recuperar todas as listas de leads com paginação
  • create-empty-list - Criar novas listas de leads ou empresas
  • get-my-network-for-sender - Obter perfis de rede para contas do LinkedIn (requer ID do remetente)

🖱️ Instalação com um clique para Cursor IDE

Comece instantaneamente com a instalação de servidor MCP com um clique do Cursor:

🌐 Servidor HTTP de produção (Recomendado)

Install in Cursor

Perfeito para acesso remoto e implantação em nuvem - Funciona com qualquer servidor HeyReach MCP implantado.

📋 Etapas de configuração:

  1. Clique no botão "Install in Cursor" acima
  2. Substitua os placeholders na configuração gerada:
    • YOUR_MCP_SERVER_URL → URL do seu servidor implantado (ex.: https://your-app.up.railway.app)
    • YOUR_HEYREACH_API_KEY_HERE → Sua chave de API real da HeyReach
  3. Salve e reinicie o Cursor para começar a usar as ferramentas HeyReach!

💻 Configuração de desenvolvimento local

Install Local in Cursor

Para desenvolvimento e testes locais - Executa o servidor HeyReach MCP via npx.

📋 Etapas de configuração:

  1. Clique no botão "Install Local in Cursor" acima
  2. Substitua o placeholder na configuração gerada:
    • YOUR_HEYREACH_API_KEY_HERE → Sua chave de API real da HeyReach
  3. Salve e reinicie o Cursor para começar a usar as ferramentas HeyReach localmente!

💡 Dica: Use a configuração HTTP de produção para melhor desempenho e ao compartilhar seu servidor MCP com n8n ou outras ferramentas.

Instalação e uso

📱 Uso local (transporte Stdio)

Via NPX (Recomendado)

npx heyreach-mcp-server --api-key=YOUR_HEYREACH_API_KEY

Via instalação global NPM

npm install -g heyreach-mcp-server
heyreach-mcp-server --api-key=YOUR_HEYREACH_API_KEY

🌐 Uso remoto (transporte por streaming HTTP)

Iniciar servidor HTTP

# Via NPX
npx heyreach-mcp-http

# Via NPM Global Install
npm install -g heyreach-mcp-server
heyreach-mcp-http

# Or with custom port
heyreach-mcp-server --http --port=3001

Uso com clientes remotos

# Health Check
curl https://your-domain.com/health

# MCP Endpoint with URL path authentication
POST https://your-domain.com/mcp/{API_KEY}
Headers:
  Content-Type: application/json
  Accept: application/json, text/event-stream

# MCP Endpoint with header authentication (NEW!)
POST https://your-domain.com/mcp
Headers:
  Content-Type: application/json
  Accept: application/json, text/event-stream
  X-API-Key: YOUR_API_KEY
  # OR
  Authorization: Bearer YOUR_API_KEY

☁️ Implantação em nuvem

Vercel (Recomendado)

git clone https://github.com/bcharleson/heyreach-mcp-server.git
cd heyreach-mcp-server
npm install
npm run build
vercel --prod

Railway

npm install -g @railway/cli
railway up

Docker

docker build -t heyreach-mcp-server .
docker run -p 3000:3000 heyreach-mcp-server

A partir do código-fonte

git clone https://github.com/bcharleson/heyreach-mcp-server.git
cd heyreach-mcp-server
npm install
npm run build

# Stdio mode
npm start -- --api-key=YOUR_HEYREACH_API_KEY

# HTTP mode
npm run start:http

Configuração

Transporte Stdio (local)

Argumentos de linha de comando

  • --api-key=YOUR_API_KEY (obrigatório): Sua chave de API da HeyReach
  • --base-url=CUSTOM_URL (opcional): URL base personalizada para a API da HeyReach

Exemplo de uso

heyreach-mcp-server --api-key=hr_1234567890abcdef --base-url=https://api.heyreach.io/api/public

Transporte HTTP (remoto)

Argumentos de linha de comando

  • --http ou --http-server: Ativar transporte por streaming HTTP
  • --port=3000 (opcional): Número da porta (padrão: 3000)

Exemplo de uso

# Start HTTP server
heyreach-mcp-server --http --port=3001

# Or use dedicated HTTP binary
heyreach-mcp-http --port=3001

Variáveis de ambiente

NODE_ENV=production
PORT=3000
CORS_ORIGIN=*
ENABLE_DNS_REBINDING_PROTECTION=true

Configuração do cliente MCP

Claude Desktop (transporte Stdio)

Adicione o seguinte ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": [
        "heyreach-mcp-server@2.0.0",
        "--api-key=YOUR_HEYREACH_API_KEY"
      ]
    }
  }
}

Integração com n8n

Opção 1: Transporte Stdio (n8n local)

✅ COMPATIBILIDADE CONFIRMADA - Todas as ferramentas funcionando com o nó MCP da comunidade n8n

  1. Instale o nó MCP da comunidade no n8n: n8n-nodes-mcp
  2. Crie credenciais de MCP Client (STDIO) no n8n:
{
  "command": "npx",
  "args": [
    "heyreach-mcp-server@2.0.0",
    "--api-key=YOUR_HEYREACH_API_KEY"
  ],
  "transport": "stdio"
}
  1. Adicione o nó MCP Client aos seus fluxos de trabalho e selecione as credenciais HeyReach
  2. Escolha entre as ferramentas disponíveis para fluxos de automação do LinkedIn

Opção 2: Transporte HTTP (n8n em nuvem)

🆕 NOVO NA v2.0.0 - Para instâncias n8n em nuvem

  1. Implante o HeyReach MCP Server na nuvem (Vercel, Railway, etc.)
  2. Use o nó HTTP Request no n8n:
{
  "url": "https://your-deployment.vercel.app/mcp/{{$env.HEYREACH_API_KEY}}",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }
}

Opção 3: MCP Client com autenticação por cabeçalho (MAIS FÁCIL!)

🆕 NOVO NA v2.0.3 - Recomendado para usuários do n8n

  1. Implante com um clique: Use os botões Railway ou Vercel acima
  2. Configure o domínio personalizado: Siga o Guia de Implantação
  3. Crie credenciais de MCP Client (HTTP) no n8n:

Configuração do MCP Client:

  • Endpoint: https://your-deployment.vercel.app/mcp
  • Transporte do servidor: HTTP Streamable
  • Autenticação: Header Auth
  • Credencial: Crie uma nova credencial com:
    • Nome: HeyReach MCP
    • X-API-Key: YOUR_HEYREACH_API_KEY

Exemplo de configuração do MCP Client no n8n:

Endpoint: https://heyreach-mcp-production.up.railway.app/mcp
Server Transport: HTTP Streamable
Authentication: Header Auth
Credential: HeyReach MCP (X-API-Key: YOUR_API_KEY)

Este método é muito mais fácil que a autenticação por caminho de URL e mais seguro!

📋 Consulte N8N_AGENT_SETUP.md para exemplos completos de fluxos de trabalho

Outros clientes MCP

Para outros clientes compatíveis com MCP (Cursor, Windsurf, ChatGPT, etc.), use a seguinte configuração:

{
  "command": "npx",
  "args": [
    "heyreach-mcp-server@2.0.0",
    "--api-key=YOUR_HEYREACH_API_KEY"
  ],
  "transport": "stdio"
}

Cursor IDE

Adicione às configurações do Cursor:

{
  "mcp": {
    "servers": {
      "heyreach": {
        "command": "npx",
        "args": ["heyreach-mcp-server", "--api-key=YOUR_HEYREACH_API_KEY"]
      }
    }
  }
}

Windsurf IDE

Adicione à configuração MCP do Windsurf:

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": ["heyreach-mcp-server", "--api-key=YOUR_HEYREACH_API_KEY"]
    }
  }
}

n8n Agent (NOVO na v1.2.3)

Para compatibilidade com n8n Agent, use variáveis de ambiente para tratamento seguro da chave de API:

Credenciais do MCP Client:

  • Comando: npx
  • Argumentos: heyreach-mcp-server@1.2.3
  • Ambiente: HEYREACH_API_KEY=YOUR_HEYREACH_API_KEY

Nó Execute Tools:

  • Parâmetros da ferramenta: Remova "Definido automaticamente pelo modelo" e use:
={{ $fromAI('tool') === 'check-api-key' ? {} : $fromAI('Tool_Parameters', `Based on the selected tool, provide the required parameters as a JSON object. If the tool requires no parameters, return an empty object {}`, 'json') }}

Configuração da chave de API

  1. Faça login na sua conta HeyReach
  2. Navegue até Configurações > Chaves de API
  3. Gere uma nova chave de API
  4. Copie a chave de API e use-a na configuração

⚠️ Nota de segurança: Nunca envie sua chave de API para o controle de versão. O servidor suporta ambos:

  • Argumentos de linha de comando (Claude Desktop): --api-key=YOUR_API_KEY
  • Variáveis de ambiente (n8n Agent): HEYREACH_API_KEY=YOUR_API_KEY

📖 Documentação das ferramentas

✅ Gerenciamento principal de campanhas

check-api-key

Verifique se sua chave de API da HeyReach é válida e está funcionando.

Parâmetros: Nenhum

Exemplo de resposta:

{
  "valid": true,
  "status": "API key is working correctly"
}

get-all-campaigns

Lista todas as campanhas na sua conta HeyReach com paginação.

Parâmetros:

  • offset (número, opcional, padrão: 0): Número de registros a pular
  • limit (número, opcional, padrão: 50): Máximo de campanhas a retornar (1-100)

Exemplo de resposta:

{
  "campaigns": [
    {
      "id": 90486,
      "name": "Test Campaign",
      "status": "DRAFT",
      "creationTime": "2025-01-24T21:30:29.037886Z",
      "campaignAccountIds": []
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 6,
    "hasMore": false
  }
}

get-campaign-details

Obtenha informações detalhadas sobre uma campanha específica.

Pré-requisitos: Use get-all-campaigns primeiro para obter IDs de campanha válidos

Parâmetros:

  • campaignId (número, obrigatório): ID da campanha de get-all-campaigns

toggle-campaign-status

Pause ou retome uma campanha.

Pré-requisitos: Use get-all-campaigns primeiro para obter IDs de campanha válidos

Parâmetros:

  • campaignId (número, obrigatório): ID da campanha
  • action (enum, obrigatório): "pause" ou "resume"

Gerenciamento de leads

add-leads-to-campaign

Adicione leads a uma campanha existente.

Parâmetros:

  • campaignId (string, obrigatório): ID da campanha de destino
  • leads (array, obrigatório): Matriz de objetos de lead com:
    • firstName (string, opcional)
    • lastName (string, opcional)
    • email (string, opcional)
    • linkedinUrl (string, opcional)
    • company (string, opcional)
    • position (string, opcional)

get-campaign-leads

Recupere leads de uma campanha com paginação.

Parâmetros:

  • campaignId (string, obrigatório): ID da campanha
  • page (número, opcional, padrão: 1): Número da página
  • limit (número, opcional, padrão: 50): Resultados por página

Mensagens

send-message

Envie uma mensagem direta para um lead.

Parâmetros:

  • leadId (string, obrigatório): ID do lead de destino
  • message (string, obrigatório): Conteúdo da mensagem
  • templateId (string, opcional): ID do modelo de mensagem

Ações sociais

perform-social-action

Execute ações sociais no LinkedIn.

Parâmetros:

  • action (enum, obrigatório): "like", "follow" ou "view"
  • targetUrl (string, obrigatório): URL de destino no LinkedIn
  • leadId (string, opcional): ID do lead associado

Análises

get-campaign-metrics

Obtenha métricas detalhadas de desempenho da campanha.

Parâmetros:

  • campaignId (string, obrigatório): ID da campanha

Exemplo de resposta:

{
  "campaignId": "camp_123",
  "totalLeads": 150,
  "contacted": 120,
  "replied": 25,
  "connected": 45,
  "responseRate": 20.8,
  "connectionRate": 37.5
}

Tratamento de erros

O servidor fornece mensagens de erro detalhadas para problemas comuns:

  • Chave de API inválida: Verifique sua chave de API e garanta que ela esteja ativa
  • Limitação de taxa: A API da HeyReach tem limites de taxa; o servidor indicará quando os limites forem excedidos
  • Parâmetros inválidos: Erros de validação detalhados para parâmetros incorretos de ferramentas
  • Problemas de rede: Tratamento de erros de conexão e tempo limite

Desenvolvimento

Pré-requisitos

  • Node.js 18+
  • npm ou yarn

Configuração

git clone https://github.com/yourusername/heyreach-mcp-server.git
cd heyreach-mcp-server
npm install

Comandos de desenvolvimento

npm run dev          # Start in development mode
npm run build        # Build for production
npm run start        # Start production build

Testes

# Test with MCP Inspector
npx @modelcontextprotocol/inspector heyreach-mcp-server --api-key=YOUR_API_KEY

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Adicione testes se aplicável
  5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Suporte

Changelog

v1.1.6 - Lançamento Pronto para Produção

  • 🎯 Taxa de Sucesso de 91,7% (11/12 ferramentas funcionando com validação abrangente)
  • ✅ 12 Ferramentas Prontas para Produção (todas validadas contra API real)
  • 🛠 Tratamento de Erros Aprimorado com validação pré-execução e orientação acionável ao usuário
  • 🌐 Suporte Universal a Clientes MCP (Claude, Cursor, Windsurf, ChatGPT, n8n, etc.)
  • 🎨 Personalização Avançada com campos personalizados e melhores práticas
  • 🔧 Validação de Status de Campanha impede adicionar leads a campanhas DRAFT
  • ➕ Nova Ferramenta get-active-campaigns para encontrar campanhas prontas para leads
  • 🔒 Parâmetros Type-Safe com validação abrangente e documentação clara
  • 📚 Dependências de Ferramentas claramente documentadas com pré-requisitos
  • 📋 Documentação de Endpoint da API relatório de validação completo para a equipe HeyReach
  • 🎯 Arquitetura Pronta para Produção com prevenção robusta de erros e orientação ao usuário