# 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
- 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. scheduler(action="on")                    → Autonomous: invitations → follow-ups → replies
5. check_replies() / show_status()           → Monitor pipeline
6. prospect(action="close", outcome="won")   → Track conversions
```

## All 30 Tools

Tools are action-routed: one tool per domain, with an `action` argument
selecting the operation (for example `campaign(action='pause')`).

### Setup & Accounts

| Tool | Description |
|------|-------------|
| `setup_profile` | Connect your LinkedIn account and analyze your writing style. Required first step. |
| `account` | Manage your LinkedIn accounts — list, switch, or disconnect. |
| `profile` | View and restore LinkedIn profile change history. |
| `network` | Network Intelligence — leverage all connected accounts as a distributed pool. |

### ICP & Targeting

| Tool | Description |
|------|-------------|
| `generate_icp` | Generate a rich Ideal Customer Profile with buyer personas. |
| `icp` | Preview which LinkedIn profiles a saved ICP matches, without creating anything. |

### Campaign Lifecycle

| Tool | Description |
|------|-------------|
| `create_campaign` | Create a LinkedIn outreach campaign from a natural language description. |
| `edit_campaign` | Edit a campaign's name, mode, booking link, or context fields. |
| `campaign` | Control campaign lifecycle — launch, monitor, pause, resume, archive, delete, emergency stop, or retry failed. |
| `import_prospects` | Import prospects from a CSV/XLSX file into a campaign. |

### Outreach Execution

| Tool | Description |
|------|-------------|
| `generate_and_send` | Generate a personalized LinkedIn message and send it (or queue for review). |
| `send_message` | Send follow-ups, replies, voice memos, or InMail to prospects. |
| `send_email` | Send an email to a prospect through a connected Gmail/Outlook mailbox. |
| `engage_prospect` | Comment on, react to, follow, or endorse a prospect on LinkedIn to build trust. |
| `book_meeting` | Book a meeting on your Google Calendar and invite a prospect. |

### Review & Approval

| Tool | Description |
|------|-------------|
| `suggest_next_action` | Suggest the best next action for your outreach. |
| `prospect` | Manage prospects — skip, close with outcome, view conversation, or timeline. |
| `contacts` | Search, browse, and manage your global contact base. |

### Inbox & Replies

| Tool | Description |
|------|-------------|
| `check_replies` | Check for new LinkedIn replies across all campaigns. |
| `inbox` | Browse and read LinkedIn inbox messages directly. |
| `backfill_inbox` | Process unreplied LinkedIn inbox messages through the inbound pipeline. |

### Analytics & Reporting

| Tool | Description |
|------|-------------|
| `show_status` | Show your outreach dashboard — campaigns, stats, hot leads, account health. |
| `analytics` | Campaign analytics — reports, comparisons, and exports. |
| `crm_sync` | Sync campaign contacts and deals to HubSpot CRM. |

### Signals & Brand

| Tool | Description |
|------|-------------|
| `signals` | View and analyze buying signals from LinkedIn. |
| `manage_watchlist` | Add, remove, and list signal keyword watchlists. |
| `create_post` | Generate and publish a voice-matched post to LinkedIn, X/Twitter, or both. |
| `brand_strategy` | Analyze and improve your LinkedIn personal brand to drive more leads. |
| `partner` | Track follow-ups with business partners, vendors, and investors. |

### Automation

| Tool | Description |
|------|-------------|
| `scheduler` | Manage the autonomous scheduler — view status or toggle on/off. Local or cloud (24/7, runs even when your laptop is off). |

## 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 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.dev/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)
