Labsco
bcharleson logo

HeyReach MCP Server

★ 5

from bcharleson

Integrates with the HeyReach API for LinkedIn automation and outreach management.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#social-media#analytics#devops#git#security#monitoring

HeyReach MCP Server

<!-- Railway deployment trigger --> v2.0.0

A modern Model Context Protocol (MCP) server with dual transport support for HeyReach LinkedIn automation. Supports both local (stdio) and remote (HTTP streaming) connections for maximum flexibility.

🚀 What's New in v2.0.0

🌐 HTTP Streaming Transport (Tested & Working)

  • Header-based Authentication: Secure X-API-KEY header authentication
  • 83% Tool Success Rate: 5/6 core tools fully tested and working
  • Session Management: Proper MCP session handling for HTTP transport
  • One-Click Install: Cursor IDE integration with deeplink installation

☁️ Cloud Deployment Ready

  • Docker Support: Multi-stage builds with security best practices
  • Vercel & Railway: Ready-to-deploy configurations
  • Health Monitoring: Built-in health check endpoints
  • Session Management: Proper session handling for HTTP transport

🔒 Production Features

  • Latest MCP SDK: Updated to v1.17.0 with latest protocol support
  • Security: DNS rebinding protection, CORS support, secure headers
  • Backward Compatibility: Existing stdio usage unchanged
  • Concurrent Sessions: Support for multiple simultaneous connections

✅ Available Tools (All Tested & Working)

🎯 Core Campaign Management

  • check-api-key - Verify API key validity
  • get-all-campaigns - List all campaigns with pagination
  • get-active-campaigns - Find campaigns ready for adding leads (ACTIVE status with LinkedIn senders)
  • get-campaign-details - Get detailed campaign information (requires campaign ID)
  • toggle-campaign-status - Pause or resume campaigns (requires campaign ID)

👥 Lead Management with Personalization

  • add-leads-to-campaign - Add LinkedIn profiles to ACTIVE campaigns with comprehensive validation and personalization support
  • get-lead-details - Get detailed lead profile information (requires LinkedIn profile URL)

💬 Conversation Management

  • get-conversations - Retrieve LinkedIn conversations with advanced filtering

📊 Analytics & Reporting

  • get-overall-stats - Get comprehensive analytics and statistics

📋 List Management

  • get-all-lists - Retrieve all lead lists with pagination
  • create-empty-list - Create new lead or company lists
  • get-my-network-for-sender - Get network profiles for LinkedIn accounts (requires sender ID)

📖 Tool Documentation

✅ Core Campaign Management

check-api-key

Verify that your HeyReach API key is valid and working.

Parameters: None

Example Response:

Copy & paste — that's it
{
  "valid": true,
  "status": "API key is working correctly"
}

get-all-campaigns

Lists all campaigns in your HeyReach account with pagination.

Parameters:

  • offset (number, optional, default: 0): Number of records to skip
  • limit (number, optional, default: 50): Maximum campaigns to return (1-100)

Example Response:

Copy & paste — that's it
{
  "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

Get detailed information about a specific campaign.

Prerequisites: Use get-all-campaigns first to get valid campaign IDs

Parameters:

  • campaignId (number, required): Campaign ID from get-all-campaigns

toggle-campaign-status

Pause or resume a campaign.

Prerequisites: Use get-all-campaigns first to get valid campaign IDs

Parameters:

  • campaignId (number, required): Campaign ID
  • action (enum, required): "pause" or "resume"

Lead Management

add-leads-to-campaign

Add leads to an existing campaign.

Parameters:

  • campaignId (string, required): Target campaign ID
  • leads (array, required): Array of lead objects with:
    • firstName (string, optional)
    • lastName (string, optional)
    • email (string, optional)
    • linkedinUrl (string, optional)
    • company (string, optional)
    • position (string, optional)

get-campaign-leads

Retrieve leads from a campaign with pagination.

Parameters:

  • campaignId (string, required): Campaign ID
  • page (number, optional, default: 1): Page number
  • limit (number, optional, default: 50): Results per page

Messaging

send-message

Send a direct message to a lead.

Parameters:

  • leadId (string, required): Target lead ID
  • message (string, required): Message content
  • templateId (string, optional): Message template ID

Social Actions

perform-social-action

Perform LinkedIn social actions.

Parameters:

  • action (enum, required): "like", "follow", or "view"
  • targetUrl (string, required): LinkedIn URL target
  • leadId (string, optional): Associated lead ID

Analytics

get-campaign-metrics

Get detailed campaign performance metrics.

Parameters:

  • campaignId (string, required): Campaign ID

Example Response:

Copy & paste — that's it
{
  "campaignId": "camp_123",
  "totalLeads": 150,
  "contacted": 120,
  "replied": 25,
  "connected": 45,
  "responseRate": 20.8,
  "connectionRate": 37.5
}

Error Handling

The server provides detailed error messages for common issues:

  • Invalid API Key: Check your API key and ensure it's active
  • Rate Limiting: HeyReach API has rate limits; the server will indicate when limits are exceeded
  • Invalid Parameters: Detailed validation errors for incorrect tool parameters
  • Network Issues: Connection and timeout error handling

Development

Prerequisites

  • Node.js 18+
  • npm or yarn

Setup

Copy & paste — that's it
git clone https://github.com/yourusername/heyreach-mcp-server.git
cd heyreach-mcp-server
npm install

Development Commands

Copy & paste — that's it
npm run dev          # Start in development mode
npm run build        # Build for production
npm run start        # Start production build

Testing

Copy & paste — that's it
# Test with MCP Inspector
npx @modelcontextprotocol/inspector heyreach-mcp-server --api-key=YOUR_API_KEY

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Changelog

v1.1.6 - Production-Ready Release

  • 🎯 91.7% Success Rate (11/12 tools working with comprehensive validation)
  • ✅ 12 Production-Ready Tools (all validated against real API)
  • 🛠 Enhanced Error Handling with pre-flight validation and actionable user guidance
  • 🌐 Universal MCP Client Support (Claude, Cursor, Windsurf, ChatGPT, n8n, etc.)
  • 🎨 Advanced Personalization with custom fields and best practices
  • 🔧 Campaign Status Validation prevents adding leads to DRAFT campaigns
  • ➕ New get-active-campaigns Tool for finding campaigns ready for leads
  • 🔒 Type-Safe Parameters with comprehensive validation and clear documentation
  • 📚 Tool Dependencies clearly documented with prerequisites
  • 📋 API Endpoint Documentation complete validation report for HeyReach team
  • 🎯 Production-Ready Architecture with robust error prevention and user guidance