Leadcraft — Gerador de Leads para Agentes IA
Lakshya330-sudo/leadcraft
Prospecção, enriquecimento e automação de outreach via slash commands
Ver no GitHubMCP server que transforma agentes IA em copiloto de vendas, descobrindo prospects na web aberta, enriquecendo dados com decision-makers reais e redigindo emails personalizados de prospecção. Funciona em Claude Code e ambientes compatíveis com MCP, sem APIs pagas, SMTP ou scraping de LinkedIn.
Instalação
npx convez-ai Lakshya330-sudo/leadcraft1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preencher pipeline de vendas com prospects qualificados automaticamente
- Gerar emails de cold outreach personalizados baseados em pesquisa web
- Rastrear e estruturar dados de leads em planilhas sem ferramentas externas pagas
Veredito

Ferramenta pragmática para equipes pequenas e freelancers que vendem via outreach. Forte em automação Web + CSV, mas requer disciplina na qualificação manual dos leads descobertos. Ideal para quem quer evitar SaaS de prospecção caros.
README
A tradução para o português deste README ainda está na fila.
leadcraft
Lead generator plugin for AI coding agents (Claude Code, OpenCode, MCP). Discover prospects, draft personalized cold outreach, track replies — no paid APIs, no SMTP, no LinkedIn scraping.
Tell the agent what you sell. It walks the open web, fills a spreadsheet with 25 prospects, deepens each one with a real decision-maker, and drafts cold email or LinkedIn DMs you can review and send from your own client.
Works in Claude Code (native plugin) and OpenCode / Hermes / any MCP-compatible harness (via the bundled MCP server).
Quickstart
npm install -g leadcraft
leads install
Then restart your AI agent and run:
/icp new # define your Ideal Customer Profile (interactive)
/find-clients # discover 25 prospects → data/leads.csv + leads.xlsx
/enrich-lead 1 # find the decision maker, recent signals, email pattern
/write-email 1 # personalized cold-email draft → data/drafts/1-YYYYMMDD.eml
Review the .eml, send it from your own mail client, then log it:
/track-outreach 1 sent
/follow-up 1 # 3 days later — bump on the same thread
/reply-suggest 1 # they replied — classify + draft 2 variants
That's the full loop. Every command above is documented below.
Table of contents
- Installation
- The 7-step workflow
- Command reference
- CLI commands (
leads ...) - How it works
- Configuration
- Hard rules — what this plugin will never do
- MCP integration (OpenCode, Hermes, etc.)
- Troubleshooting
- Roadmap
- Contributing
- License
Installation
Option 1 — npm (recommended)
npm install -g leadcraft
leads install
This places the plugin's markdown files at ~/.claude/plugins/leads/ and bootstraps the empty data directory. Restart Claude Code (or your agent) and the 17 slash commands appear.
To install to a custom location:
leads install --target=./my-leads
Option 2 — Manual (git clone)
git clone https://github.com/Lakshya330-sudo/leadcraft.git
cd leadcraft
npm install # installs deps + builds the MCP server
node bin/leads.js install # copies plugin to ~/.claude/plugins/leads/
Option 3 — Symlink for development
git clone https://github.com/Lakshya330-sudo/leadcraft.git
ln -s "$(pwd)/leadcraft" ~/.claude/plugins/leads
Edits to the cloned repo are picked up immediately.
The 7-step workflow
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ 1. /icp new Define who you sell to │
│ ↓ │
│ 2. /find-clients Discover 25 matching companies │
│ ↓ │
│ 3. /enrich-lead <id> Find the decision maker + signals │
│ ↓ │
│ 4. /write-email <id> Draft personalized cold outreach │
│ ↓ │
│ 5. (you send the email from your own client — plugin never sends) │
│ ↓ │
│ 6. /track-outreach Log sent → opened → replied → booked │
│ ↓ │
│ 7. /follow-up Day-3 bump, day-7 reframe, day-14 break-up │
│ │
└──────────────────────────────────────────────────────────────────────────┘
State lives on disk under data/:
leads.csv— canonical store, one row per prospectleads.xlsx— auto-regenerated mirror for Excel usersoutreach.json— append-only event log per leadicps/<slug>.json— saved Ideal Customer Profilesdrafts/<id>-<date>.eml— every email draft
Command reference
All 17 commands. Each links to its full markdown body.
Discovery & qualification
| Command | What it does |
|---|---|
/icp | Define, list, or activate an Ideal Customer Profile. Interactive — asks 8 questions and writes data/icps/<slug>.json. |
/find-clients | The headline command. Constructs 6 web-search queries from the active ICP (buying signals + directory + long-tail), parses 25 companies off their own homepages, writes to leads.csv. |
/qualify-leads | Score every row's fit_score (0–100) against the active ICP using the 6-component rubric. Re-sorts the spreadsheet by fit. |
/enrich-lead | Deep-dive on one row: walks /team, /about, /careers, /blog (4-fetch budget), finds the decision maker, infers email pattern, appends buying signals. |
/find-decision-maker | Focused alternative when /enrich-lead came up short. Tries company pages → wider web search → generates a LinkedIn search URL for manual click-through. Accepts an <id> or a free-text company name. |
/research-company | Pre-meeting one-pager. Walks 6 pages and produces a markdown brief: what they do, size & stage, recent moves, tech stack, people to know, likely pains, 3 conversation openers. Doesn't touch leads.csv unless you pass --save. |
Outreach
| Command | What it does |
|---|---|
/write-email | Personalized cold-email draft. Three variants: intro (default, 4-part hook→relevance→ask→CTA), value (lead with outcome), casual (peer tone for founder-stage). 120-word body cap, 60-char subject cap, deliverability checklist enforced before save. |
/follow-up | Auto-picks day-3 / day-7 / break-up based on days-since-last-touch. Day-3 stays on the same thread; day-7 starts a new thread with a different angle; day-14 is the no-guilt-trip break-up. Refuses if the lead has already replied or the sequence is exhausted. |
/draft-linkedin | LinkedIn DM variant — 300-char hard cap, no signature, mobile-preview-aware (first 80 chars must contain the hook). Generates the LinkedIn search URL for manual sending (plugin never opens LinkedIn). |
/reply-suggest | Paste an incoming reply. Classifies it into 7 categories (interested-warm, interested-cold, objection, not-now, wrong-person, unsubscribe, auto-reply), drafts two response variants with class-specific tone rules, side-effects status update. |
Data operations
| Command | What it does |
|---|---|
/track-outreach | Log a status change: sent, opened, replied, booked, lost, nurture. Validates the state-machine transition before writing. Atomic dual-write to outreach.json + leads.csv. |
/verify-emails | Regex + DNS MX check. No SMTP probe — too noisy, hurts sender IP reputation. Caches MX results per domain within a run. Writes verdict to notes (email-ok / email-mx-missing / email-syntax-bad). |
/dedupe-leads | Merge duplicate rows by domain (default) or email. Survivor chosen by status rank → fit score → most-recent enrichment. Migrates event history from duplicates with a synthetic merge event. |
/import-leads | Import an external CSV or XLSX. Auto-detects column mapping (with confirmation prompts for ambiguous ones), normalizes domains, dedupes against existing rows, assigns fresh IDs. |
/export-crm | Export a CRM-shaped CSV. Three formats: HubSpot (Lifecycle Stage mapping), Pipedrive (Deal Stage), Salesforce (Lead Status, with [Unknown] last-name fallback). Strips ~ from guessed emails for CRM compatibility. |
Meta
| Command | What it does |
|---|---|
/lead-stats | Read-only pipeline dashboard. ASCII bar-chart funnel, sent→replied / sent→booked rates, median time-to-reply, stalled-leads call-to-action list, top-ICPs leaderboard, data-quality warnings tied to specific remediation commands. |
/lead-config | View / set plugin defaults — default_n, output format (csv/xlsx/both), source allow/deny list, signature block. |
CLI commands (leads ...)
The npm install puts a leads binary on your PATH. Use it for plugin lifecycle, not lead-gen workflow (that's the slash commands).
| Command | Purpose |
|---|---|
leads install | Copy plugin to ~/.claude/plugins/leads/ (override with --target=<path>, force with --force) |
leads uninstall | Remove the installed plugin (doesn't touch the npm package itself) |
leads mcp | Run the MCP server over stdio. Configure your MCP client to launch this command. |
leads where | Print the resolved install path |
leads doctor | Diagnose install state — checks all required files + the MCP server build |
leads version | Print plugin version |
leads help | Show this catalogue |
How it works
Pure markdown by design
This plugin has no runtime. Slash commands are markdown files; skills (the agent's reference manual) are markdown files; templates (cold-email skeletons) are markdown files. The agent — Claude or any LLM in your harness — reads them and drives the workflow with its native tool calls (WebSearch, WebFetch, Read, Write).
Benefits:
- Zero install friction for Claude Code users — drop the folder, restart, done.
- No background processes, no API keys, no SMTP credentials at risk.
- Source code IS the prompt — when you tweak
commands/write-email.md, the next run uses your edits immediately.
The cost: portability beyond Claude Code requires a wrapper. That's what mcp-server/ is.
File layout
leadcraft/
├── .claude-plugin/plugin.json # manifest
├── CLAUDE.md # agent operating guide (data contracts, source policy, status state machine)
├── commands/ # 17 slash commands
├── skills/ # 6 reference skills (lead-discovery, email-personalization, outreach-tracking, ...)
├── templates/ # 7 email/DM templates
├── data/ # generated at runtime — gitignored
│ ├── leads.csv # canonical store (source of truth)
│ ├── leads.xlsx # derived view, auto-regenerated
│ ├── outreach.json # append-only event log per lead
│ ├── icps/<slug>.json # saved Ideal Customer Profiles
│ ├── icps/_active.txt # which ICP is currently active
│ └── drafts/<id>-<date>.eml # every draft, never sent
├── mcp-server/ # optional Node MCP wrapper (Phase 7)
├── bin/leads.js # the npm CLI
└── package.json # npm-installable
Status state machine
Every lead has one status from this set:
new → enriched → drafted → sent ──┬─→ opened
├─→ replied ──┬─→ booked
│ ├─→ lost
│ └─→ nurture
└─(no reply, time-based)→ (still "sent")
Follow-ups are events, not status changes. A lead at sent who got a day-3 bump is still sent. Full transition table in skills/outreach-tracking/SKILL.md.
Configuration
data/config.json (created on demand by /lead-config):
{
"default_n": 25,
"output_format": "both",
"source_allowlist": [],
"source_denylist": ["upwork.com", "fiverr.com", "linkedin.com"],
"default_signature": "",
"max_leads_per_run": 100,
"follow_up_days": [3, 7, 14]
}
Edit via /lead-config set <key> <value> or by hand.
Hard rules — what this plugin will never do
These are baked into every command and skill. They're not bugs, they're the contract.
| ❌ | Why |
|---|---|
| Send emails — drafts only | Drafts give you a review step. Sending requires credentials we don't want to manage. |
| Scrape LinkedIn / X / Facebook | Violates ToS. Where useful, the plugin generates search URLs for you to open manually. |
| Call paid APIs (Apollo, Clearbit, Hunter, ZoomInfo) | The plugin works for free out of the box. Add paid sources later if you want — but not in v1. |
| Fabricate facts | Empty cells are fine. Made-up contacts, fake fit-notes, hallucinated "buying signals" are not. |
| SMTP-probe email deliverability | Damages sender reputation. /verify-emails does syntax + DNS MX only. |
Mutate leads.csv non-atomically | Every write is temp-file + rename. No partial-state corruption. |
Overwrite fit_notes or notes | Always appended with ; separator. History matters. |
| Skip the deliverability checklist before saving a draft | A failing draft is worse than no draft. |
MCP integration (OpenCode, Hermes, etc.)
For non-Claude-Code harnesses, run the bundled MCP server:
leads mcp
It exposes:
- 16 tools — primitives for
leads.csv/outreach.json/ ICPs / drafts (CRUD) - 17 prompts — every slash command, re-exposed by name
- Read-only resources — every skill, template, and command markdown file under
leads://
Add to your MCP client config (example for Claude Desktop / OpenCode):
{
"mcpServers": {
"leads": {
"command": "leads",
"args": ["mcp"]
}
}
}
Full details: mcp-server/README.md.
Architecture note: the MCP server reads and writes the same
data/directory Claude Code does. You can use both surfaces in parallel — they stay in sync via the filesystem.
Troubleshooting
leads install says "Target already exists"
leads uninstall && leads install
# or
leads install --force
leads mcp says "MCP server not built"
If you cloned from git:
npm install # triggers the workspace build
If you installed from npm and see this, please open an issue — the build should be pre-shipped.
data/leads.xlsx doesn't regenerate
The plugin's pure-markdown side falls back gracefully — leads.csv is canonical and Excel opens CSV directly. To enable xlsx output, the markdown side tries Python+openpyxl or PowerShell ImportExcel. The MCP server uses bundled exceljs and always works.
"No active ICP" errors
Run /icp new to define one, or /icp use <slug> to activate an existing one.
Commands don't appear after leads install
Restart your AI agent. Claude Code reads ~/.claude/plugins/ at startup.
Roadmap
The plugin shipped in 7 phases. All are complete:
| Phase | Surface | Status |
|---|---|---|
| 0 | Plugin skeleton + /icp + data contracts | ✅ |
| 1 | /find-clients discovery | ✅ |
| 2 | xlsx generation | ✅ |
| 3 | /write-email + 3 cold-email variants + 4 follow-up/breakup templates | ✅ |
| 4 | Enrichment trio: /enrich-lead, /find-decision-maker, /research-company | ✅ |
| 5 | Tracking & follow-up loop: /track-outreach, /follow-up, /reply-suggest, /draft-linkedin | ✅ |
| 6 | Quality & data ops: /qualify-leads, /verify-emails, /dedupe-leads, /import-leads, /export-crm, /lead-stats | ✅ |
| 7 | MCP server for non-Claude harnesses | ✅ |
Full design history in CLAUDE.md. Future ideas tracked in GitHub issues.
Contributing
Contributions welcome — especially:
- New buying-signal patterns in
skills/lead-discovery/SKILL.md - New cold-email templates in
templates/ - CRM export formats beyond HubSpot/Pipedrive/Salesforce
- ICP scoring-rubric improvements in
skills/icp-management/SKILL.md
Before submitting:
git clone https://github.com/Lakshya330-sudo/leadcraft.git
cd leadcraft
npm install
node bin/leads.js doctor # sanity-check
Open a PR against main. No CLA, no formal process — just clear changes and a one-paragraph "why."
License
MIT © Lakshya Rawat
Built with Claude Code. Designed to work everywhere Claude Code doesn't — via MCP.