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 or Claude Code — any MCP-compatible AI editor.

Step 1: Install HeyLead

Install in Cursor

Click the link above and Cursor installs it automatically. HeyLead runs in the cloud — no local install, no updates, always the latest version.

Manual install or using another editor?

Cursor (manual): Settings > MCP > "Add new MCP server" > Type: URL, Name: heylead, URL: https://heylead.dev/mcp

Claude Code:

claude mcp add heylead --transport http https://heylead.dev/mcp

Any MCP client (streamable-http):

{
  "heylead": {
    "type": "url",
    "url": "https://heylead.dev/mcp"
  }
}

OpenClaw: Add to your openclaw.json:

{
  "mcp": {
    "servers": [
      {
        "name": "heylead",
        "type": "url",
        "url": "https://heylead.dev/mcp"
      }
    ]
  }
}

Or install from ClawHub: search "HeyLead"

Prefer local install? (offline/self-hosted)

If you need offline access or want to self-host, you can run HeyLead locally via stdio:

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

Claude Code: claude mcp add heylead -- uvx heylead

Any MCP client:

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

Note: local installs require uv and need uvx --refresh heylead to update.

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

• Define your ICP — "Generate an ICP for AI SaaS founders" → RAG-powered personas with pain points, barriers, and LinkedIn targeting
• Create a campaign — "Find me fintech CTOs" → searches LinkedIn, scores prospects by fit
• Warm up prospects — Engages with their posts (comments, likes) before reaching out
• Send personalized invitations — Voice-matched messages that sound like you, not a bot
• Follow up automatically — Multi-touch sequences after connections are accepted
• Handle replies — Detects sentiment, advances positive leads toward meetings, answers questions
• 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

• AI calls — routed through HeyLead's backend (Gemini 2.0 Flash) or your own key
• Cloud MCP — your data is processed server-side but never shared with third parties
• Local mode — contacts and messages stay on your machine in a local SQLite database

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:

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.

Publishing to PyPI (maintainers)

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

Option A: Publish via GitHub Release (recommended)

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

Option B: Publish manually

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 (recommended — cloud, always up to date):

{
  "heylead": {
    "type": "url",
    "url": "https://heylead.dev/mcp"
  }
}

Local install (offline/self-hosted):

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

OpenClaw: Add to your openclaw.json under mcp.servers:

{
  "name": "heylead",
  "type": "url",
  "url": "https://heylead.dev/mcp"
}

Also available on ClawHub — 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.

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

See AGENTS.md for the full agent integration guide.

Links

• PyPI
• MCP Registry
• Smithery
• ClawHub (OpenClaw skill store)
• Issues

License

MIT (code) — see LICENSE

Knowledge base and prompt configurations are proprietary.