npm package: @flipfactory-it/mcp-leadgen
Description: MCP Lead Gen — zero-cost AI-powered lead generation using DuckDuckGo search, website scraping, email pattern finder, and export. No API keys required.
Author: FlipFactory
Latest version: 2.0.2

# @flipfactory-it/mcp-leadgen

[![npm version](https://img.shields.io/npm/v/@flipfactory-it/mcp-leadgen)](https://www.npmjs.com/package/@flipfactory-it/mcp-leadgen)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](.)

Zero-cost lead generation MCP server. Search businesses via DuckDuckGo, scrape contact info from websites, find email addresses by pattern matching, and export leads -- all without API keys.

## Quick Start

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "leadgen": {
      "command": "npx",
      "args": ["@flipfactory-it/mcp-leadgen"]
    }
  }
}
```

No environment variables or API keys required.

## Tools

### `business_search`

Search for businesses using DuckDuckGo and optionally scrape each result page for contact details.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | Yes | -- | Search query (e.g., "law firms in Kyiv", "dentists in Miami") |
| `limit` | number | No | 10 | Max results, 1-20 |
| `enrichDetails` | boolean | No | false | Fetch each result URL for phone/email/address extraction |

**Returns:** name, URL, snippet. With `enrichDetails: true`, also phone, email, and address when found on the page.

### `contact_enrich`

Scrape a website URL for contact information: emails, phones, social links, address, and metadata.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string (URL) | Yes | Website URL to scrape (e.g., "https://example.com") |

**Returns:** emails, phones, social links (Facebook, LinkedIn, Twitter, Instagram, YouTube, Telegram), address (from JSON-LD or itemprop), page title, and meta description.

### `email_find`

Find probable email addresses using common pattern matching and MX record verification.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firstName` | string | Yes | First name of the person |
| `lastName` | string | Yes | Last name of the person |
| `domain` | string | Yes | Company domain (e.g., "acme.com") |

**Returns:** list of email candidates with confidence scores (high/medium/low), the pattern used, MX record validity, and a best guess.

### `export`

Export collected leads to JSON or CSV format.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `leads` | array | Yes | -- | Array of lead objects (each needs `name` and `company` at minimum) |
| `format` | "json" or "csv" | No | "json" | Export format |
| `filename` | string | No | auto-generated | Custom filename (without extension) |

**Lead object fields:** `name`, `email`, `phone`, `company`, `website`, `address`, `city`, `state`, `country`, `industry`, `source`, `rating`, `linkedinUrl`.

**Returns:** formatted data string, count, and filename.

## Examples

### Search for businesses

```
"Find dentists in Miami, FL"
-> business_search(query: "dentists in Miami, FL", limit: 20)
```

### Search with contact enrichment

```
"Find law firms in Kyiv with their contact info"
-> business_search(query: "law firms in Kyiv", limit: 10, enrichDetails: true)
```

### Scrape a website for contact info

```
"Get contact details from https://acme-marketing.com"
-> contact_enrich(url: "https://acme-marketing.com")
```

### Find someone's email

```
"Find John Doe's email at acme.com"
-> email_find(firstName: "John", lastName: "Doe", domain: "acme.com")
```

### Export leads to CSV

```
"Export these leads as CSV"
-> export(leads: [...], format: "csv")
```

### Full workflow

```
1. business_search(query: "marketing agencies in Austin, TX", enrichDetails: true)
2. contact_enrich(url: "https://acme-marketing.com")
3. email_find(firstName: "John", lastName: "Smith", domain: "acme-marketing.com")
4. export(leads: [...], format: "csv")
```

## Built-in Features

- **Zero Cost** -- Uses DuckDuckGo search and web scraping, no paid API keys needed
- **Rate Limiting** -- Per-tool limits (10 searches/min, 15 enrichments/min, 30 email lookups/min)
- **Caching** -- 1-hour cache for searches, 24-hour for enrichment and email lookups
- **Smart Defaults** -- Minimal required params, sensible defaults for the rest
- **Structured Output** -- Typed JSON responses, easy to parse and chain
- **Helpful Errors** -- Clear messages when rate limits are hit or requests fail

## Development

```bash
npm install
npm run dev      # Watch mode
npm test         # Run tests
npm run build    # Compile TypeScript
```

## License

MIT -- [FlipFactory](https://flipfactory.it)