HeyReach MCP Server

Se integra con la API de HeyReach para la automatización de LinkedIn y la gestión de alcance.

GitHub
5
Prueba este MCPPatrocinado

Documentación

HeyReach MCP Server

v2.0.0

Un servidor moderno de Model Context Protocol (MCP) con soporte de transporte dual para la automatización de LinkedIn de HeyReach. Admite conexiones locales (stdio) y remotas (streaming HTTP) para máxima flexibilidad.

🚀 Novedades en v2.0.0

🌐 Transporte de Streaming HTTP (Probado y Funcionando)

  • Autenticación basada en cabeceras: Autenticación segura mediante cabecera X-API-KEY
  • 83% de tasa de éxito en herramientas: 5/6 herramientas principales completamente probadas y funcionando
  • Gestión de sesiones: Manejo adecuado de sesiones MCP para transporte HTTP
  • Instalación con un clic: Integración con Cursor IDE mediante instalación con deeplink

☁️ Listo para despliegue en la nube

  • Soporte Docker: Builds multi-etapa con mejores prácticas de seguridad
  • Vercel y Railway: Configuraciones listas para desplegar
  • Monitoreo de salud: Endpoints de verificación de estado integrados
  • Gestión de sesiones: Manejo adecuado de sesiones para transporte HTTP

🔒 Funciones de producción

  • Último SDK de MCP: Actualizado a v1.17.0 con el soporte de protocolo más reciente
  • Seguridad: Protección contra DNS rebinding, soporte CORS, cabeceras seguras
  • Compatibilidad hacia atrás: El uso existente de stdio no cambia
  • Sesiones concurrentes: Soporte para múltiples conexiones simultáneas

🚀 Despliegue en la nube con un clic

Despliega tu HeyReach MCP Server en la nube al instante con configuración automática de protección contra DNS rebinding:

🚂 Railway (Recomendado para n8n)

Deploy on Railway

Perfecto para integración con n8n - Configuración automática del entorno con ${{RAILWAY_PUBLIC_DOMAIN}}.

📋 Pasos rápidos de despliegue:

  1. Haz clic en "Deploy on Railway" en el botón de arriba
  2. Inicia sesión en Railway (conecta GitHub si es necesario)
  3. Selecciona "Deploy from GitHub repo" en el menú desplegable
  4. Busca: bcharleson/heyreach-mcp
  5. Haz clic en Deploy - Railway detecta automáticamente la configuración de railway.toml
  6. ¡Listo! Tu servidor MCP estará en línea con configuración DNS automática

🎯 Resultado: https://your-app.up.railway.app listo para integración con n8n

▲ Vercel (Despliegue más rápido)

Deploy with Vercel

Despliegue global en el edge - HTTPS instantáneo y soporte de dominios personalizados.

📋 Después del despliegue: Sigue la Guía de despliegue para configurar dominios personalizados y probar la integración con n8n.

✅ Herramientas disponibles (Todas probadas y funcionando)

🎯 Gestión principal de campañas

  • check-api-key - Verifica la validez de la clave API
  • get-all-campaigns - Lista todas las campañas con paginación
  • get-active-campaigns - Encuentra campañas listas para añadir leads (estado ACTIVE con remitentes de LinkedIn)
  • get-campaign-details - Obtén información detallada de la campaña (requiere ID de campaña)
  • toggle-campaign-status - Pausa o reanuda campañas (requiere ID de campaña)

👥 Gestión de leads con personalización

  • add-leads-to-campaign - Añade perfiles de LinkedIn a campañas ACTIVE con validación integral y soporte de personalización
  • get-lead-details - Obtén información detallada del perfil del lead (requiere URL del perfil de LinkedIn)

💬 Gestión de conversaciones

  • get-conversations - Recupera conversaciones de LinkedIn con filtrado avanzado

📊 Analítica e informes

  • get-overall-stats - Obtén analítica y estadísticas completas

📋 Gestión de listas

  • get-all-lists - Recupera todas las listas de leads con paginación
  • create-empty-list - Crea nuevas listas de leads o empresas
  • get-my-network-for-sender - Obtén perfiles de red para cuentas de LinkedIn (requiere ID de remitente)

🖱️ Instalación con un clic para Cursor IDE

Empieza al instante con la instalación de servidor MCP con un clic de Cursor:

🌐 Servidor HTTP de producción (Recomendado)

Install in Cursor

Perfecto para acceso remoto y despliegue en la nube - Funciona con cualquier servidor HeyReach MCP desplegado.

📋 Pasos de configuración:

  1. Haz clic en "Install in Cursor" en el botón de arriba
  2. Reemplaza los marcadores de posición en la configuración generada:
    • YOUR_MCP_SERVER_URL → La URL de tu servidor desplegado (p. ej., https://your-app.up.railway.app)
    • YOUR_HEYREACH_API_KEY_HERE → Tu clave API real de HeyReach
  3. Guarda y reinicia Cursor para empezar a usar las herramientas de HeyReach.

💻 Configuración de desarrollo local

Install Local in Cursor

Para desarrollo y pruebas locales - Ejecuta el servidor HeyReach MCP mediante npx.

📋 Pasos de configuración:

  1. Haz clic en "Install Local in Cursor" en el botón de arriba
  2. Reemplaza el marcador de posición en la configuración generada:
    • YOUR_HEYREACH_API_KEY_HERE → Tu clave API real de HeyReach
  3. Guarda y reinicia Cursor para empezar a usar las herramientas de HeyReach localmente.

💡 Consejo: Usa la configuración HTTP de producción para mejor rendimiento y al compartir tu servidor MCP con n8n u otras herramientas.

Instalación y uso

📱 Uso local (transporte Stdio)

Mediante NPX (Recomendado)

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

Mediante instalación global de NPM

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

🌐 Uso remoto (transporte de 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 con 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

☁️ Despliegue en la nube

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

Desde el código fuente

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

Configuración

Transporte Stdio (local)

Argumentos de línea de comandos

  • --api-key=YOUR_API_KEY (obligatorio): Tu clave API de HeyReach
  • --base-url=CUSTOM_URL (opcional): URL base personalizada para la API de HeyReach

Ejemplo de uso

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

Transporte HTTP (remoto)

Argumentos de línea de comandos

  • --http o --http-server: Habilita el transporte de streaming HTTP
  • --port=3000 (opcional): Número de puerto (por defecto: 3000)

Ejemplo de uso

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

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

Variables de entorno

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

Configuración del cliente MCP

Claude Desktop (transporte Stdio)

Añade lo siguiente a tu archivo de configuración de 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"
      ]
    }
  }
}

Integración con n8n

Opción 1: Transporte Stdio (n8n local)

✅ COMPATIBILIDAD CONFIRMADA - Todas las herramientas funcionan con el nodo MCP de la comunidad de n8n

  1. Instala el nodo MCP de la comunidad en n8n: n8n-nodes-mcp
  2. Crea credenciales de MCP Client (STDIO) en n8n:
{
  "command": "npx",
  "args": [
    "heyreach-mcp-server@2.0.0",
    "--api-key=YOUR_HEYREACH_API_KEY"
  ],
  "transport": "stdio"
}
  1. Añade el nodo MCP Client a tus flujos de trabajo y selecciona las credenciales de HeyReach
  2. Elige entre las herramientas disponibles para flujos de trabajo de automatización de LinkedIn

Opción 2: Transporte HTTP (n8n en la nube)

🆕 NUEVO EN v2.0.0 - Para instancias de n8n basadas en la nube

  1. Despliega HeyReach MCP Server en la nube (Vercel, Railway, etc.)
  2. Usa el nodo HTTP Request en 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"
  }
}

Opción 3: MCP Client con autenticación por cabecera (¡LA MÁS FÁCIL!)

🆕 NUEVO EN v2.0.3 - Recomendado para usuarios de n8n

  1. Despliega con un clic: Usa los botones de Railway o Vercel de arriba
  2. Configura un dominio personalizado: Sigue la Guía de despliegue
  3. Crea credenciales de MCP Client (HTTP) en n8n:

Configuración del MCP Client:

  • Endpoint: https://your-deployment.vercel.app/mcp
  • Server Transport: HTTP Streamable
  • Authentication: Header Auth
  • Credential: Crea una nueva credencial con:
    • Name: HeyReach MCP
    • X-API-Key: YOUR_HEYREACH_API_KEY

Ejemplo de configuración de MCP Client en 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 es mucho más fácil que la autenticación por ruta URL y más seguro!

📋 Consulta N8N_AGENT_SETUP.md para ver ejemplos completos de flujos de trabajo

Otros clientes MCP

Para otros clientes compatibles con MCP (Cursor, Windsurf, ChatGPT, etc.), usa la siguiente configuración:

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

Cursor IDE

Añade a la configuración de Cursor:

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

Windsurf IDE

Añade a la configuración MCP de Windsurf:

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

n8n Agent (NUEVO en v1.2.3)

Para compatibilidad con n8n Agent, usa variables de entorno para el manejo seguro de la clave API:

Credenciales del MCP Client:

  • Command: npx
  • Arguments: heyreach-mcp-server@1.2.3
  • Environment: HEYREACH_API_KEY=YOUR_HEYREACH_API_KEY

Nodo Execute Tools:

  • Tool Parameters: Elimina "Defined automatically by the model" y usa:
={{ $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') }}

Configuración de la clave API

  1. Inicia sesión en tu cuenta de HeyReach
  2. Ve a Settings > API Keys
  3. Genera una nueva clave API
  4. Copia la clave API y úsala en la configuración

⚠️ Nota de seguridad: Nunca subas tu clave API al control de versiones. El servidor admite ambos:

  • Argumentos de línea de comandos (Claude Desktop): --api-key=YOUR_API_KEY
  • Variables de entorno (n8n Agent): HEYREACH_API_KEY=YOUR_API_KEY

📖 Documentación de herramientas

✅ Gestión principal de campañas

check-api-key

Verifica que tu clave API de HeyReach sea válida y funcione.

Parámetros: Ninguno

Ejemplo de respuesta:

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

get-all-campaigns

Lista todas las campañas de tu cuenta de HeyReach con paginación.

Parámetros:

  • offset (número, opcional, por defecto: 0): Número de registros a omitir
  • limit (número, opcional, por defecto: 50): Máximo de campañas a devolver (1-100)

Ejemplo de respuesta:

{
  "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

Obtén información detallada sobre una campaña específica.

Requisitos previos: Usa get-all-campaigns primero para obtener IDs de campaña válidos

Parámetros:

  • campaignId (número, obligatorio): ID de campaña de get-all-campaigns

toggle-campaign-status

Pausa o reanuda una campaña.

Requisitos previos: Usa get-all-campaigns primero para obtener IDs de campaña válidos

Parámetros:

  • campaignId (número, obligatorio): ID de campaña
  • action (enum, obligatorio): "pause" o "resume"

Gestión de leads

add-leads-to-campaign

Añade leads a una campaña existente.

Parámetros:

  • campaignId (cadena, obligatorio): ID de la campaña de destino
  • leads (array, obligatorio): Array de objetos de lead con:
    • firstName (cadena, opcional)
    • lastName (cadena, opcional)
    • email (cadena, opcional)
    • linkedinUrl (cadena, opcional)
    • company (cadena, opcional)
    • position (cadena, opcional)

get-campaign-leads

Recupera leads de una campaña con paginación.

Parámetros:

  • campaignId (cadena, obligatorio): ID de campaña
  • page (número, opcional, por defecto: 1): Número de página
  • limit (número, opcional, por defecto: 50): Resultados por página

Mensajería

send-message

Envía un mensaje directo a un lead.

Parámetros:

  • leadId (cadena, obligatorio): ID del lead de destino
  • message (cadena, obligatorio): Contenido del mensaje
  • templateId (cadena, opcional): ID de la plantilla de mensaje

Acciones sociales

perform-social-action

Realiza acciones sociales en LinkedIn.

Parámetros:

  • action (enum, obligatorio): "like", "follow" o "view"
  • targetUrl (cadena, obligatorio): URL de LinkedIn de destino
  • leadId (cadena, opcional): ID de lead asociado

Analítica

get-campaign-metrics

Obtén métricas detalladas de rendimiento de la campaña.

Parámetros:

  • campaignId (cadena, obligatorio): ID de campaña

Ejemplo de respuesta:

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

Manejo de errores

El servidor proporciona mensajes de error detallados para problemas comunes:

  • Clave API no válida: Comprueba tu clave API y asegúrate de que esté activa
  • Límite de velocidad: La API de HeyReach tiene límites de velocidad; el servidor indicará cuando se superen los límites
  • Parámetros no válidos: Errores de validación detallados para parámetros incorrectos de herramientas
  • Problemas de red: Manejo de errores de conexión y tiempo de espera

Desarrollo

Requisitos previos

  • Node.js 18+
  • npm o yarn

Configuración

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

Comandos de desarrollo

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

Pruebas

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

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad
  3. Realiza tus cambios
  4. Añade pruebas si corresponde
  5. Envía una solicitud de pull

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Soporte

Historial de cambios

v1.1.6 - Lanzamiento listo para producción

  • 🎯 91.7% de éxito (11/12 herramientas funcionando con validación integral)
  • ✅ 12 herramientas listas para producción (todas validadas contra la API real)
  • 🛠 Manejo de errores mejorado con validación previa y guía de usuario accionable
  • 🌐 Soporte universal de clientes MCP (Claude, Cursor, Windsurf, ChatGPT, n8n, etc.)
  • 🎨 Personalización avanzada con campos personalizados y mejores prácticas
  • 🔧 Validación de estado de campaña evita agregar leads a campañas en DRAFT
  • ➕ Nueva herramienta get-active-campaigns para encontrar campañas listas para leads
  • 🔒 Parámetros con seguridad de tipos con validación integral y documentación clara
  • 📚 Dependencias de herramientas claramente documentadas con requisitos previos
  • 📋 Documentación de endpoints de API informe de validación completo para el equipo de HeyReach
  • 🎯 Arquitectura lista para producción con prevención robusta de errores y guía de usuario