heyreach-mcp-campaign

A Model Context Protocol (MCP) server providing full API coverage for HeyReach LinkedIn automation — including the new Campaign API for programmatic campaign creation.

Features

• Full Campaign API — Create, configure, start/pause/resume campaigns programmatically
• Sequence Builder — Define automation workflows with connection requests, messages, InMails, conditions
• Lead Management — Add leads to campaigns/lists with custom personalization fields
• List Management — Create and manage lead/company lists
• LinkedIn Accounts — View connected senders
• Inbox — Read conversations and send messages

Available Tools (26 total)

| Tool | Description | |------|-------------| | check_api_key | Verify API key validity | | get_all_campaigns | List campaigns with pagination | | get_campaign_by_id | Get campaign details | | get_campaign_sequence | Get campaign workflow tree | | create_campaign | Create a new campaign (DRAFT) | | update_campaign_settings | Update name, list, exclusions | | update_campaign_sequence | Replace campaign workflow | | update_campaign_accounts | Replace sender accounts | | update_campaign_schedule | Replace schedule config | | start_campaign | Activate a draft campaign | | pause_campaign | Pause an active campaign | | resume_campaign | Resume a paused campaign | | add_leads_to_campaign | Add leads to active campaign (v2) | | get_leads_from_list | Get leads from a list | | get_lists_for_lead | Find which lists contain a lead | | stop_lead_in_campaign | Stop a lead mid-campaign | | get_companies_from_list | Get companies from a company list | | get_all_lists | List all lead/company lists | | create_list | Create empty list | | add_leads_to_list | Add leads to a list (v2) | | get_all_linkedin_accounts | List connected senders | | get_conversations | Read inbox conversations | | send_message | Send a LinkedIn message | | get_overall_stats | Get performance stats (daily + totals) | | get_lead_tags | Get tags for a lead | | add_lead_tags | Add tags to a lead |

Installation

Via npx (quickest)

npx heyreach-mcp-campaign

From source

git clone https://github.com/oxtx/heyreach-mcp-campaign.git
cd heyreach-mcp-campaign
npm install
npm run build
npm start

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": ["heyreach-mcp-campaign"],
      "env": {
        "HEYREACH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": ["heyreach-mcp-campaign"],
      "env": {
        "HEYREACH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor / Windsurf

Same format in your MCP settings:

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": ["heyreach-mcp-campaign"],
      "env": {
        "HEYREACH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage Examples

Create a campaign with a connection request → message sequence

Use create_campaign with:
- name: "CMO Outreach Q1"
- listId: 12345
- accountIds: [111, 222]
- sequence: {
    nodeType: "CONNECTION_REQUEST",
    actionDelay: 0,
    actionDelayUnit: "HOUR",
    payload: { messages: ["Hi {FIRST_NAME}, I'd love to connect!"], fallbackMessage: "Hi, I'd love to connect!" },
    conditionalNode: {
      nodeType: "MESSAGE",
      actionDelay: 1,
      actionDelayUnit: "DAY",
      payload: {
        messages: ["Thanks for connecting, {FIRST_NAME}! I wanted to share..."],
        fallbackMessage: "Thanks for connecting! I wanted to share..."
      },
      conditionalNode: { nodeType: "END", actionDelay: 0, actionDelayUnit: "HOUR" },
      unconditionalNode: { nodeType: "END", actionDelay: 1, actionDelayUnit: "DAY" }
    },
    unconditionalNode: { nodeType: "END", actionDelay: 14, actionDelayUnit: "DAY" }
  }

Then call start_campaign with the returned campaignId.

Add leads from Clay/external source

Use add_leads_to_campaign with:
- campaignId: 12345
- leads: [
    {
      profileUrl: "https://linkedin.com/in/johndoe",
      firstName: "John",
      lastName: "Doe",
      company: "Acme Inc",
      customFields: { "icebreaker": "Loved your recent post about AI" }
    }
  ]

API Key Setup

1. Log in to your HeyReach account at app.heyreach.io
2. Click the gear icon (Settings) in the bottom-left sidebar
3. Go to Integrations tab
4. Scroll to the API Keys section
5. Click "New API Key"
6. Give it a name (e.g. "MCP Server") and click Create
7. Copy the generated key immediately — it won't be shown again

Use it via environment variable (recommended):

export HEYREACH_API_KEY=your_key_here

Or via CLI argument:

npx heyreach-mcp-campaign --api-key=your_key_here

Note: API keys are tied to your workspace. If you manage multiple workspaces (agency accounts), each workspace has its own key.

Sequence Node Types

| Type | Description | Requires both branches? | |------|-------------|------------------------| | CONNECTION_REQUEST | Send connection request | Yes (conditional + unconditional) | | MESSAGE | Send message to connection | Yes (replied + no reply) | | INMAIL | Send InMail | No | | LIKE_POST | Like a lead's post | No | | CHECK_IS_CONNECTION | Branch on connection status | Yes | | CHECK_IS_OPEN_PROFILE | Branch on Open Profile | Yes | | SEND_LEAD_TO_INSTANTLY | Export to Instantly | No | | SEND_LEAD_TO_SMARTLEAD | Export to Smartlead | No | | END | Terminal node | N/A |

Payload Format

| Node Type | Payload | |-----------|---------| | CONNECTION_REQUEST | { messages: ["note text"], fallbackMessage: "fallback", toBeWithdrawnAfterDays?: number } — use [""] for no note | | MESSAGE | { messages: ["message text"], fallbackMessage: "used when personalization fails" } | | INMAIL | { subject: "subject", messages: ["body"], fallbackMessage: "fallback body" } | | LIKE_POST | {} (no payload needed) | | END | no payload needed |

Important: messages is always an array (even for a single message). fallbackMessage is the version used when personalization variables like {FIRST_NAME} can't be resolved.

Sequence Rules

• Every path must terminate with an END node
• actionDelayUnit is required: "HOUR" or "DAY"
• Minimum 3 hours delay between action nodes (use actionDelayUnit: "DAY" with value >= 1)
• END nodes after a conditional (replied) path can use actionDelay: 0, actionDelayUnit: "HOUR"
• END nodes after unconditional (no reply) path should use actionDelay >= 1, actionDelayUnit: "DAY"

License

MIT