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
HeyLead runs locally over stdio. You need uv:
Claude Code:
claude mcp add heylead -- uvx heylead
Cursor: Settings > MCP > "Add new MCP server" > Name: heylead, Command: uvx heylead
Any MCP client:
{
"heylead": {
"command": "uvx",
"args": ["heylead"]
}
}
Update with uvx --refresh heylead.
Step 2: Set up your account
Option A — Hosted (easiest): sign in at heylead.dev/auth/login-url with Google, connect LinkedIn, and copy the message it shows you. Paste that message into your AI chat — HeyLead finishes setup automatically. LinkedIn access and AI calls are handled by the HeyLead backend; no API keys needed.
Option B — Self-hosted: run everything against your own accounts. You need two things first:
- A Unipile account — this is what talks to LinkedIn. Sign up at
unipile.com, then put the DSN and API key from
the Access Tokens page into
~/.heylead/config.jsonasunipile_api_urlandunipile_api_key. - An LLM API key — AI calls are billed to you. A free Gemini key is enough to start.
Then open your AI chat and say:
"Set up my HeyLead profile with this Gemini key: YOUR_KEY"
You'll get a LinkedIn authentication link. Open it, connect LinkedIn, then say "finish setup". HeyLead fetches your profile and analyses your writing style.
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
Safety model: campaigns are created as drafts and only start when you explicitly launch them. Every send passes rate limits, working-hours checks, and a 1st-degree connection guard before it goes out.
Tools
HeyLead gives your AI 27 tools:
Core Workflow
| Tool | What it does |
|---|---|
setup_profile |
Connects LinkedIn and analyzes your writing style into a voice signature |
generate_icp |
Generates a rich Ideal Customer Profile with buyer personas |
create_campaign |
Creates an outreach campaign (as a draft) from a natural language description |
generate_and_send |
Generates a personalized LinkedIn message and sends it |
check_replies |
Checks for new replies across campaigns, classifies sentiment, surfaces hot leads |
show_status |
Your dashboard — campaigns, stats, hot leads, account health |
Outreach & Engagement
| Tool | What it does |
|---|---|
send_message |
Sends follow-ups, replies, or voice memos to prospects |
engage_prospect |
Comments on, reacts to, follows, or endorses a prospect to build trust |
inbox |
Browses and reads LinkedIn inbox messages directly |
backfill_inbox |
Processes unreplied inbox messages through the inbound pipeline |
create_post |
Generates and publishes a voice-matched post to LinkedIn, X/Twitter, or both |
Campaign Management
| Tool | What it does |
|---|---|
campaign |
Campaign lifecycle — launch, pause, resume, archive, delete, emergency stop, retry failed |
edit_campaign |
Edits a campaign's name, mode, booking link, or context fields |
prospect |
Manages prospects — skip, close with outcome, view conversation or timeline |
import_prospects |
Imports prospects from CSV data into a campaign |
Insights & Analytics
| Tool | What it does |
|---|---|
analytics |
Campaign analytics — reports, comparisons, and exports |
suggest_next_action |
Recommends the best next action, prioritized by impact |
signals |
Views and analyzes buying signals — news, company engagement, website visits, profile viewers |
manage_watchlist |
Adds, removes, and lists signal keyword watchlists |
network |
Network intelligence — leverages all connected accounts as a distributed pool |
Growth & Relationships
| Tool | What it does |
|---|---|
brand_strategy |
Analyzes and improves your LinkedIn personal brand |
profile |
Views and restores LinkedIn profile change history |
partner |
Tracks follow-ups with business partners, vendors, and investors |
contacts |
Searches, browses, and manages your global contact base |
crm_sync |
Syncs campaign contacts and deals to HubSpot CRM |
Automation & Account
| Tool | What it does |
|---|---|
scheduler |
Manages the autonomous scheduler — status, on/off (local or cloud 24/7) |
account |
Manages LinkedIn accounts — list, switch, or disconnect |
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 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_TOKENwith 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.ymlruns 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 (stdio):
{
"heylead": {
"command": "uvx",
"args": ["heylead"]
}
}
OpenClaw: Add the same entry to your openclaw.json under mcp.servers.
Also available on ClawHub — search "HeyLead".
Sign in at heylead.dev (hosted), or bring your own Unipile account and LLM API key (self-hosted).
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.
27 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file heylead-0.10.186.tar.gz.
File metadata
- Download URL: heylead-0.10.186.tar.gz
- Upload date:
- Size: 909.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4f5eb5342f34087a4ca5aa45a3fd547bef42ee2662b0653fc0313c99fd82c8b1
|
|
| MD5 |
e93dc0cfc3a399f963efb2f52cba63d9
|
|
| BLAKE2b-256 |
27da1e76e32333ebf5f7b3b0cbe49399da77b648e8770f2a86ff30946f04a5a1
|
File details
Details for the file heylead-0.10.186-py3-none-any.whl.
File metadata
- Download URL: heylead-0.10.186-py3-none-any.whl
- Upload date:
- Size: 900.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
17a82933e96ed32a9cee64ba16887f15ce093165e285a96c70104b94b216e091
|
|
| MD5 |
3f01d4ee896500437a9b519887848b7b
|
|
| BLAKE2b-256 |
1f4789eb7f6b483029fa1e2c191e5ae5e5cd65d221abc9bb975a57d0597696b5
|
