# @bingeljell/lead-gen-mcp

MCP server for AI-assisted B2B lead generation. Discover, extract, score, and export company leads — from any MCP-compatible agent (Claude Desktop, Cursor, Windsurf, Codex, etc.).

## Context

- This started as a lead pipeline inside [Alfred](https://github.com/bingeljell/alfredAI) — a personal AI agent built for outbound sales work
- Extracted into a standalone MCP server so anyone selling to small and mid-sized businesses can use it with their agent of choice
- Works across agents — not Claude-specific
- **Still under active development.** See [docs/release_notes.md](docs/release_notes.md) for what's in each release

## Tools

| Tool | What it does |
|------|-------------|
| `lead_discover` | Search for companies matching a query and rank them by ICP fit. No browser required. |
| `lead_extract` | Deep-extract a single company's name, emails, industry, and size from a URL via headless browser. |
| `lead_generate` | Full pipeline: search → rank → extract → filter → save to CSV. |

## Requirements

- Node.js ≥ 20
- A search provider — SearXNG (self-hosted), Brave API key, or nothing (falls back to DuckDuckGo automatically)
- An LLM key (Anthropic or OpenAI) — optional but improves extraction quality

## Setup

### Option A — Use via npx (no clone needed)

The server runs on demand. Just configure your agent to call it with `npx`:

```json
"command": "npx",
"args": ["-y", "@bingeljell/lead-gen-mcp"]
```

### Option B — Clone and build locally

```bash
git clone https://github.com/bingeljell/lead-gen-mcp
cd lead-gen-mcp
npm install
npx playwright install chromium   # one-time ~130MB browser download
npm run build
```

Point your agent at the built file:

```json
"command": "node",
"args": ["/absolute/path/to/lead-gen-mcp/dist/server.js"]
```

---

## Agent configuration

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lead-gen": {
      "command": "npx",
      "args": ["-y", "@bingeljell/lead-gen-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8888",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "LEAD_GEN_OUTPUT_DIR": "/Users/you/leads"
      }
    }
  }
}
```

Restart Claude Desktop. The three tools appear automatically.

### Cursor / Windsurf

Same config format — add to your MCP settings JSON and restart the editor.

### OpenAI Agents SDK (Codex)

```python
from agents import Agent
from agents.mcp import MCPServerStdio

lead_gen = MCPServerStdio(
    command="npx",
    args=["-y", "@bingeljell/lead-gen-mcp"],
    env={
        "SEARXNG_BASE_URL": "http://localhost:8888",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "LEAD_GEN_OUTPUT_DIR": "./leads"
    }
)

agent = Agent(name="LeadResearcher", mcp_servers=[lead_gen])
```

### Claude Code (CLI)

```bash
claude mcp add lead-gen \
  -e SEARXNG_BASE_URL=http://localhost:8888 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e LEAD_GEN_OUTPUT_DIR=/Users/you/leads \
  npx -y @bingeljell/lead-gen-mcp
```

---

## Environment variables

```bash
# Search — set at least one (falls back to DuckDuckGo if none set)
SEARXNG_BASE_URL=http://localhost:8888   # self-hosted SearXNG
BRAVE_SEARCH_API_KEY=                    # https://api.search.brave.com

# LLM — optional, improves extraction accuracy
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

# Output directory for CSVs
LEAD_GEN_OUTPUT_DIR=./leads
```

Copy `.env.example` for a template.

---

## ICP profiles

The `profile` parameter tunes candidate ranking for different buyer types:

| Profile | Target |
|---------|--------|
| `generic` | Any business |
| `msp` | Managed service providers (IT/cybersecurity) |
| `si` | Systems integrators / Microsoft partners |
| `event_planner` | Event planning / wedding businesses |

## Example prompts

> "Find 10 MSPs in Austin, Texas and save their contact emails."

> "Search for small systems integrators in the UK, vertical msp_uk, max 5 leads."

> "Discover event planning companies in Chicago — profile: event_planner."

## License

MIT