HeyReach MCP Server

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

🚀 One-Click Cloud Deployment

Deploy your HeyReach MCP Server to the cloud instantly with automatic DNS rebinding protection configuration:

🚂 Railway (Recommended for n8n)

Perfect for n8n integration - Automatic environment configuration with ${{RAILWAY_PUBLIC_DOMAIN}}.

📋 Quick Deploy Steps:

1. Click "Deploy on Railway" button above
2. Sign in to Railway (connect GitHub if needed)
3. Select "Deploy from GitHub repo" from the dropdown
4. Search for: bcharleson/heyreach-mcp
5. Click Deploy - Railway auto-detects railway.toml configuration
6. Done! Your MCP server will be live with automatic DNS configuration

🎯 Result: https://your-app.up.railway.app ready for n8n integration

▲ Vercel (Fastest Deployment)

Global edge deployment - Instant HTTPS and custom domain support.

📋 Post-deployment: Follow the Deployment Guide to configure custom domains and test n8n integration.

✅ 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)

🖱️ One-Click Install for Cursor IDE

Get started instantly with Cursor's one-click MCP server installation:

🌐 Production HTTP Server (Recommended)

Perfect for remote access and cloud deployment - Works with any deployed HeyReach MCP server.

📋 Setup Steps:

1. Click "Install in Cursor" button above
2. Replace placeholders in the generated config:
   • YOUR_MCP_SERVER_URL → Your deployed server URL (e.g., https://your-app.up.railway.app)
   • YOUR_HEYREACH_API_KEY_HERE → Your actual HeyReach API key
3. Save and restart Cursor to start using HeyReach tools!

💻 Local Development Setup

For local development and testing - Runs HeyReach MCP server via npx.

📋 Setup Steps:

1. Click "Install Local in Cursor" button above
2. Replace placeholder in the generated config:
   • YOUR_HEYREACH_API_KEY_HERE → Your actual HeyReach API key
3. Save and restart Cursor to start using HeyReach tools locally!

💡 Tip: Use the Production HTTP setup for better performance and when sharing your MCP server with n8n or other tools.

Installation & Usage

📱 Local Usage (Stdio Transport)

Via NPX (Recommended)

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

Via NPM Global Install

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

🌐 Remote Usage (HTTP Streaming Transport)

Start HTTP Server

# 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

Usage with Remote Clients

# 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

☁️ Cloud Deployment

Vercel (Recommended)

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

From Source

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

Configuration

Stdio Transport (Local)

Command Line Arguments

• --api-key=YOUR_API_KEY (required): Your HeyReach API key
• --base-url=CUSTOM_URL (optional): Custom base URL for the HeyReach API

Example Usage

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

HTTP Transport (Remote)

Command Line Arguments

• --http or --http-server: Enable HTTP streaming transport
• --port=3000 (optional): Port number (default: 3000)

Example Usage

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

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

Environment Variables

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

MCP Client Configuration

Claude Desktop (Stdio Transport)

Add the following to your Claude Desktop configuration file:

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"
      ]
    }
  }
}

n8n Integration

Option 1: Stdio Transport (Local n8n)

✅ CONFIRMED COMPATIBLE - All tools working with n8n community MCP node

1. Install the community MCP node in n8n: n8n-nodes-mcp
2. Create MCP Client (STDIO) credentials in n8n:

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

3. Add MCP Client node to your workflows and select HeyReach credentials
4. Choose from available tools for LinkedIn automation workflows

Option 2: HTTP Transport (Cloud n8n)

🆕 NEW IN v2.0.0 - For cloud-based n8n instances

1. Deploy HeyReach MCP Server to cloud (Vercel, Railway, etc.)
2. Use HTTP Request node in 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"
  }
}

Option 3: MCP Client with Header Authentication (EASIEST!)

🆕 NEW IN v2.0.3 - Recommended for n8n users

1. Deploy with one-click: Use the Railway or Vercel buttons above
2. Configure custom domain: Follow the Deployment Guide
3. Create MCP Client (HTTP) credentials in n8n:

MCP Client Configuration:

• Endpoint: https://your-deployment.vercel.app/mcp
• Server Transport: HTTP Streamable
• Authentication: Header Auth
• Credential: Create a new credential with:
  • Name: HeyReach MCP
  • X-API-Key: YOUR_HEYREACH_API_KEY

Example n8n MCP Client Setup:

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)

This method is much easier than URL path authentication and more secure!

📋 See N8N_AGENT_SETUP.md for complete workflow examples

Other MCP Clients

For other MCP-compatible clients (Cursor, Windsurf, ChatGPT, etc.), use the following configuration:

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

Cursor IDE

Add to your Cursor settings:

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

Windsurf IDE

Add to your Windsurf MCP configuration:

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

n8n Agent (NEW in v1.2.3)

For n8n Agent compatibility, use environment variables for secure API key handling:

MCP Client Credentials:

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

Execute Tools Node:

• Tool Parameters: Remove "Defined automatically by the model" and 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') }}

API Key Setup

1. Log in to your HeyReach account
2. Navigate to Settings > API Keys
3. Generate a new API key
4. Copy the API key and use it in the configuration

⚠️ Security Note: Never commit your API key to version control. The server supports both:

• Command-line arguments (Claude Desktop): --api-key=YOUR_API_KEY
• Environment variables (n8n Agent): HEYREACH_API_KEY=YOUR_API_KEY

📖 Tool Documentation

✅ Core Campaign Management

check-api-key

Verify that your HeyReach API key is valid and working.

Parameters: None

Example Response:

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

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

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

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

Development Commands

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

Testing

# 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

• Issues: GitHub Issues
• Documentation: HeyReach API Docs
• MCP Specification: Model Context Protocol

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