<!-- mcp-name: io.github.D4umak/heylead -->
# HeyLead

**Your AI sales rep. One command to fill your pipeline.**

HeyLead is an MCP-native autonomous LinkedIn SDR that runs inside Cursor, Claude Code, or any MCP-compatible editor. No dashboard. No web app. Just chat with your AI and say "find me leads."

---

## Getting Started

MCP (Model Context Protocol) lets AI assistants use external tools. HeyLead gives your AI the ability to do LinkedIn outreach for you.

**You need:** [Cursor](https://cursor.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — any MCP-compatible AI editor.

### Step 1: Install HeyLead

[**Install in Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=heylead&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJoZXlsZWFkIl19)

Click the link above and Cursor installs it automatically.

<details>
<summary>Manual install or using another editor?</summary>

**Cursor (manual):** Settings > MCP > "Add new MCP server" > Name: `heylead`, Command: `uvx heylead`

**Claude Code:** `claude mcp add heylead -- uvx heylead`

**OpenClaw:** Add to your `openclaw.json`:
```json
{
  "mcp": {
    "servers": [
      {
        "name": "heylead",
        "command": "uvx",
        "args": ["heylead"]
      }
    ]
  }
}
```
Or install from [ClawHub](https://clawhub.ai): search "HeyLead"
</details>

### Step 2: Set up your account

Open your AI chat and say:

> **"Set up my HeyLead profile"**

You'll get a link — sign in with Google, connect LinkedIn, copy your token, paste it back. ~1 minute, no API keys needed.

### Step 3: Find leads

```
"Find me CTOs at fintech startups in New York"
"Send outreach to the campaign"
"Check my replies"
"How's my outreach doing?"
```

---

## 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) 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** (default) — review every message before it sends
- **Autopilot** — AI handles outreach within your rate limits and working hours

---

## Tools

HeyLead gives your AI 31 specialized tools:

### Core Workflow

| Tool | What it does |
|------|-------------|
| `setup_profile` | Connects LinkedIn and creates your voice signature |
| `generate_icp` | Creates rich Ideal Customer Profiles with buyer personas, pain points, and LinkedIn targeting |
| `create_campaign` | Finds prospects matching your target and builds a campaign |
| `generate_and_send` | Writes personalized invitations and sends (or queues for review) |
| `check_replies` | Checks for new replies, classifies sentiment, surfaces hot leads |
| `show_status` | Your dashboard — campaigns, stats, hot leads, account health |

### Multi-Touch Outreach

| Tool | What it does |
|------|-------------|
| `send_followup` | Sends follow-up DMs after a connection is accepted |
| `reply_to_prospect` | Auto-replies adapting to sentiment — advance meetings, answer questions, or gracefully close |
| `engage_prospect` | Comments on or reacts to a prospect's LinkedIn posts for warm-up |

### Copilot Review

| Tool | What it does |
|------|-------------|
| `approve_outreach` | Approve, edit, skip, or stop a proposed message |
| `suggest_next_action` | AI recommends what to do next, prioritized by impact |
| `show_conversation` | View the full message thread with a prospect |

### Campaign Management

| Tool | What it does |
|------|-------------|
| `edit_campaign` | Update name, mode, booking link, offerings, or messaging preferences |
| `pause_campaign` | Pause outreach on a campaign |
| `resume_campaign` | Resume a paused campaign |
| `archive_campaign` | Mark a campaign as completed |
| `skip_prospect` | Remove a bad-fit prospect from the queue |
| `retry_failed` | Retry outreaches that failed with errors |
| `emergency_stop` | Immediately pause all active campaigns |

### Analytics

| Tool | What it does |
|------|-------------|
| `campaign_report` | Detailed analytics — funnel, outcomes, stale leads, engagement ROI |
| `export_campaign` | Export campaign results as a formatted table |
| `compare_campaigns` | Side-by-side comparison of multiple campaigns |
| `close_outreach` | Record outcome — won, lost, or opted out |

### Automation

| Tool | What it does |
|------|-------------|
| `toggle_scheduler` | Enable autonomous outreach (local or cloud 24/7) |
| `scheduler_status` | View scheduler state, pending jobs, recent activity |

### Account

| Tool | What it does |
|------|-------------|
| `list_linkedin_accounts` | List connected LinkedIn accounts (read-only) |
| `switch_account` | List accounts and switch flow |
| `switch_account_to` | Switch to a different LinkedIn account |
| `unlink_account` | Disconnect LinkedIn and clear local account |

---

## Key Features

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

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

**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** — Automatically engages with prospect posts before sending connection requests, building familiarity.

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

**Outcome Tracking** — Mark deals as won/lost, track conversion rates, identify stale leads, measure engagement ROI.

---

## 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
- We don't store your messages or contacts on our servers

> **Power users:** Pass your own LLM key (Gemini/Claude/OpenAI) during setup to use your own AI. Completely optional.

---

## Backend mode & env

When the MCP client talks to a HeyLead backend (e.g. `heylead-api`), the backend uses these environment variables. Operators running their own backend should set them as required.

| Purpose | Example env vars |
|--------|-------------------|
| LLM | `GEMINI_API_KEY`, or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` if using other providers |
| Search / crawl | `SERPER_API_KEY`, `FIRECRAWL_API_KEY` (or similar) for ICP and company context |
| Auth / storage | `GOOGLE_*` (OAuth), `UNIPILE_*` (LinkedIn provider), plus DB/Redis if used |
| Optional | Feature flags, rate limits, logging — see backend repo |

For full backend configuration and deployment, see the **heylead-api** (or backend) repo and its docs.

---

## Optional Dependencies

The base install covers all core features. For advanced ICP generation:

```bash
pip install heylead[icp]    # Embeddings for RAG-powered ICP generation
pip install heylead[crawl]  # Web crawling for company context ingestion
pip install heylead[all]    # Both
```

---

## Troubleshooting

**"uvx: command not found"**
Install `uv` first: `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `brew install uv` on Mac)

**"MCP server not connecting"**
Restart your editor after adding the MCP server. In Cursor, check Settings > MCP — the server should show a green dot.

**"Setup failed" or "LinkedIn not connected"**
Make sure you clicked "Connect LinkedIn Now" on the sign-in page and completed the LinkedIn login. Then run setup again.

**Need help?** Open an [issue](https://github.com/D4umak/heylead/issues).

---

## Publishing to PyPI (maintainers)

To make HeyLead available on PyPI (or to publish a new version):

### Option A: Publish via GitHub Release (recommended)

1. **One-time:** Create a [PyPI account](https://pypi.org/account/register/) and an [API token](https://pypi.org/manage/account/token/). In your repo: **Settings → Secrets and variables → Actions** → add secret `PYPI_TOKEN` with the token value.
2. Bump version in `pyproject.toml` (`version = "0.2.4"`).
3. Commit, push, then create a **GitHub Release** (tag e.g. `v0.2.4`, release title optional). The workflow [`.github/workflows/publish.yml`](.github/workflows/publish.yml) runs on release and publishes to PyPI.

### Option B: Publish manually

```bash
pip install build twine
python -m build          # creates dist/
twine check dist/*       # optional: validate
twine upload dist/*      # prompts for PyPI username + password (use __token__ and your API token)
```

After publishing, anyone can install with `pip install heylead` or run with `uvx heylead`.

---

## For AI Agents

HeyLead is designed as an MCP-native tool — built for AI agents, not humans clicking buttons.

**Install as MCP server:**
```json
{
  "heylead": {
    "command": "uvx",
    "args": ["heylead"]
  }
}
```

**OpenClaw:** Add to your `openclaw.json` under `mcp.servers`:
```json
{
  "name": "heylead",
  "command": "uvx",
  "args": ["heylead"]
}
```
Also available on [ClawHub](https://clawhub.ai) — search "HeyLead" for one-click install.

**Capabilities:** LinkedIn lead generation, cold outreach automation, ICP generation with buyer personas, voice-matched personalized messaging, multi-touch drip sequences, reply sentiment classification, engagement warm-ups, campaign analytics, and autonomous 24/7 scheduling.

**31 tools** covering the full SDR workflow: prospect discovery → outreach → follow-up → reply handling → deal closing.

See [`AGENTS.md`](AGENTS.md) for the full agent integration guide.

---

## Links

- [PyPI](https://pypi.org/project/heylead/)
- [MCP Registry](https://registry.modelcontextprotocol.io)
- [Smithery](https://smithery.ai)
- [ClawHub](https://clawhub.ai) (OpenClaw skill store)
- [Issues](https://github.com/D4umak/heylead/issues)

## License

MIT (code) — see [LICENSE](LICENSE)

Knowledge base and prompt configurations are proprietary.
