# HeyLead — Complete Documentation

> MCP-native autonomous LinkedIn SDR — AI-powered lead generation, voice-matched cold outreach, multi-touch drip sequences, and campaign analytics inside Cursor, Claude Code, or any MCP client.

## What is HeyLead?

HeyLead is an autonomous LinkedIn SDR (Sales Development Representative) that runs entirely via MCP (Model Context Protocol) tools. It finds prospects on LinkedIn, sends personalized outreach that sounds like you wrote it, follows up automatically, tracks replies with sentiment classification, and closes deals — all through natural language commands.

No dashboard. No web app. Just tell your AI "find me CTOs at fintech startups" and watch it work.

HeyLead is designed for founders, sales teams, and anyone who needs to fill their pipeline with qualified leads from LinkedIn without spending hours on manual outreach.

## How It Works

1. **Define your ICP** — "Generate an ICP for AI SaaS founders" — RAG-powered personas with pain points, barriers, and LinkedIn targeting
2. **Create a campaign** — "Find me fintech CTOs" — searches LinkedIn, scores prospects by fit
3. **Warm up prospects** — Engages with their posts (comments, likes, follows, endorsements) before reaching out
4. **Send personalized invitations** — Voice-matched messages that sound like you, not a bot
5. **Follow up automatically** — Multi-touch sequences after connections are accepted
6. **Handle replies** — Detects sentiment, advances positive leads toward meetings, answers questions
7. **Track outcomes** — Won/lost/opted-out tracking with conversion analytics

**Two modes:**
- **Copilot** — review every message before it sends
- **Autopilot** — AI handles outreach within your rate limits and working hours

## Installation

### Cursor (one-click)

[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=heylead&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJoZXlsZWFkIl19) — click the link and Cursor installs it automatically.

### Cursor (manual)

Settings > MCP > "Add new MCP server" > Name: `heylead`, Command: `uvx heylead`

### Claude Code

```
claude mcp add heylead -- uvx heylead
```

### Any MCP client (manual)

```json
{
  "heylead": {
    "command": "uvx",
    "args": ["heylead"]
  }
}
```

### pip

```
pip install heylead
```

## Authentication

- Google OAuth — sign in, connect LinkedIn, copy your JWT token
- Pass token to `setup_profile(backend_jwt="...")` — that's it
- No API keys needed — backend proxies LLM calls (Gemini 2.0 Flash)
- Optional: bring your own key (Gemini/Claude/OpenAI) via `setup_profile(llm_api_key="...")`

## Typical Workflow

```
1. setup_profile(backend_jwt="...")          → Connect LinkedIn account
2. generate_icp(target="CTOs at fintech")    → Create buyer personas
3. create_campaign(target="...", icp_id="...") → Find prospects, start outreach
4. toggle_scheduler(enabled=True)            → Autonomous: invitations → follow-ups → replies
5. check_replies() / show_status()           → Monitor pipeline
6. close_outreach(outcome="won")             → Track conversions
```

## All 31 Tools

### Setup & Accounts

| Tool | Description |
|------|-------------|
| `setup_profile` | Connect LinkedIn, analyze writing style, create voice signature. Required first step. |
| `list_linkedin_accounts` | List all connected LinkedIn accounts |
| `switch_account` | Show accounts and start switch flow |
| `switch_account_to` | Switch to a specific LinkedIn account by ID |
| `unlink_account` | Disconnect LinkedIn from HeyLead |

### ICP & Targeting

| Tool | Description |
|------|-------------|
| `generate_icp` | Create Ideal Customer Profiles with buyer personas, pain points, fears, barriers, and LinkedIn search parameters. RAG-powered with company context crawling. |

### Campaign Lifecycle

| Tool | Description |
|------|-------------|
| `create_campaign` | Create a LinkedIn outreach campaign from a natural language description. Finds prospects, scores by fit. Accepts optional `icp_id` from `generate_icp`. |
| `edit_campaign` | Update campaign name, mode, booking link, offerings, case studies, or messaging preferences |
| `pause_campaign` | Pause an active campaign, stopping all outreach |
| `resume_campaign` | Resume a paused campaign |
| `archive_campaign` | Mark a campaign as completed |
| `delete_campaign` | Permanently delete a campaign and all its data |

### Outreach Execution

| Tool | Description |
|------|-------------|
| `generate_and_send` | Generate and send personalized LinkedIn invitation. Voice-matched cold outreach. Autopilot sends automatically; Copilot queues for review. |
| `send_followup` | Send follow-up DM after connection accepted. Part of multi-touch drip sequences. |
| `reply_to_prospect` | Auto-reply to prospect messages. Detects sentiment — positive replies advance toward meetings, questions get contextual answers, negative replies get graceful close. |
| `engage_prospect` | Comment on, react to, follow, or endorse a prospect on LinkedIn. Social selling warm-up before cold outreach. Actions: auto, comment, react/like, follow, endorse. |

### Review & Approval

| Tool | Description |
|------|-------------|
| `approve_outreach` | Approve, reject, edit, or skip a copilot-generated message. Actions: yes/send, skip, edit, stop, react, close_happy/won, close_unhappy/lost, opt_out. |
| `suggest_next_action` | AI recommends the best next action, prioritized by impact: hot leads first, then pending approvals, follow-ups, engagements, new invitations. |
| `show_conversation` | View the full DM thread and engagement history with a prospect |
| `skip_prospect` | Remove a bad-fit prospect from the outreach queue |

### Analytics & Reporting

| Tool | Description |
|------|-------------|
| `show_status` | Your dashboard — campaigns, stats, hot leads, account health, SSI score, InMail balance. |
| `check_replies` | Check for new LinkedIn replies, inbound invitations, and profile viewers. Classifies sentiment, surfaces hot leads. |
| `campaign_report` | Detailed analytics — funnel, outcomes, stale leads, engagement ROI, conversion rates. |
| `export_campaign` | Export campaign results as a formatted table (copy-paste friendly) |
| `compare_campaigns` | Side-by-side comparison of 2+ campaigns with winner highlights for each metric |
| `close_outreach` | Record outcome — won, lost, or opted out — with conversion analytics |
| `experiment_loop` | Analyze performance and generate experiment hypotheses for A/B testing |

### Automation

| Tool | Description |
|------|-------------|
| `toggle_scheduler` | Enable/disable autonomous scheduler. Local or cloud (24/7, runs even when laptop is off). |
| `scheduler_status` | View scheduler state, pending jobs, recent activity, cloud scheduler status |
| `emergency_stop` | Immediately pause ALL active campaigns — kill switch |
| `retry_failed` | Retry outreaches that failed with errors |

## Key Features

**Voice Matching** — Analyzes your LinkedIn profile and posts to capture your writing style. Every message sounds like you wrote it, not a bot.

**ICP Generation** — RAG-powered pipeline that crawls company context, generates buyer personas with pain points, fears, barriers, and maps them to LinkedIn search parameters with confidence scores.

**Autonomous Scheduler** — Runs in the background, respects working hours and rate limits. Enable cloud scheduling for 24/7 operation even when your laptop is off.

**Engagement Warm-ups** — Full warm-up sequence before cold outreach: Follow → Endorse skills → Comment/like posts → Send invitation → Follow-up DM → InMail (if no accept).

**Adaptive Rate Limiting** — Starts conservative, ramps up when acceptance rate is high, pulls back when it drops. Respects LinkedIn safety limits with time-based cooldowns.

**Outcome Tracking** — Mark deals as won/lost, track conversion rates, identify stale leads, measure engagement ROI. Full funnel analytics from prospect to closed deal.

**Company Enrichment** — Fetches company data (industry, size, employee count, specialties) before generating messages for better personalization.

**InMail Support** — Send InMail to prospects who don't accept connection requests. InMail balance shown in dashboard.

## Pricing

| Plan | Price | What you get |
|------|-------|-------------|
| **Free** | $0 | 50 invitations/month, 1 campaign, 2 follow-ups per prospect, 30 engagements/month |
| **Pro** | $29/mo | Unlimited campaigns, 5 follow-ups with multi-day schedule, 5 LinkedIn accounts, cloud scheduler |

## Privacy

Your data stays on your machine:
- Contacts and messages — local SQLite database
- AI calls — routed through HeyLead's backend (Gemini 2.0 Flash) or your own key
- HeyLead does not store your messages or contacts on its servers

Power users can pass their own LLM key (Gemini/Claude/OpenAI) during setup to use their own AI. Completely optional.

## Transport

- **stdio** (default) — for local MCP clients (Cursor, Claude Code, etc.)
- **streamable-http** — remote endpoint at `https://heylead-api-141730336364.us-central1.run.app/mcp`

## MCP Server Configuration

```json
{
  "heylead": {
    "command": "uvx",
    "args": ["heylead"]
  }
}
```

## Use Cases

- **Founders** — "Find me 50 CTOs at Series A fintech startups in New York and send them a connection request about our API product"
- **Sales teams** — "Create an ICP for enterprise HR directors, then launch a campaign targeting them"
- **Agencies** — "Switch to [client account], check replies, follow up with hot leads"
- **Recruiters** — "Find senior engineers at AI startups, send personalized outreach about our open roles"

## Links

- PyPI: https://pypi.org/project/heylead/
- GitHub: https://github.com/D4umak/heylead
- MCP Registry: https://registry.modelcontextprotocol.io
- Smithery: https://smithery.ai
- Issues: https://github.com/D4umak/heylead/issues
- License: MIT (code)
