# LeadBrew MCP Server

<p align="center">
  <img src="https://leadbrew.co/assets/images/logo.png" alt="LeadBrew" width="200">
</p>

<p align="center">
  <strong>Access millions of B2B leads directly from your AI coding assistant</strong>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#supported-assistants">Supported Assistants</a> •
  <a href="#available-tools">Tools</a> •
  <a href="#examples">Examples</a> •
  <a href="#api-reference">API Reference</a>
</p>

---

LeadBrew MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI coding assistants access to the LeadBrew B2B lead database. Search for leads, get contact information, and find companies—all through natural language.

## Features

- **Millions of B2B Leads** - Access verified business contacts with emails and phone numbers
- **Company Database** - Search companies by industry, size, and location
- **Real-time Search** - Find leads by name, title, company, or industry
- **Free Tier** - 100 leads/day included with every account
- **Works Everywhere** - Compatible with Claude Code, Cursor, Windsurf, and more

## Quick Start

### 1. Get Your API Credentials

1. Sign up at [leadbrew.co](https://leadbrew.co)
2. Go to **Settings** → **API Access**
3. Click **Generate API Key**
4. Save your `API Key` and `API Secret`

### 2. Install the MCP Server

```bash
# Clone the repository
git clone https://github.com/FlatNineOrg/leadbrew-mcp.git
cd leadbrew-mcp

# Install dependencies
npm install

# Build the server
npm run build
```

### 3. Configure Your AI Assistant

See [configuration instructions](#supported-assistants) for your specific assistant.

## Supported Assistants

### Claude Code (Anthropic)

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "leadbrew": {
      "command": "node",
      "args": ["/path/to/leadbrew-mcp/dist/index.js"],
      "env": {
        "LEADBREW_API_KEY": "lb_your_api_key_here",
        "LEADBREW_API_SECRET": "your_api_secret_here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (Settings → MCP Servers):

```json
{
  "leadbrew": {
    "command": "node",
    "args": ["/path/to/leadbrew-mcp/dist/index.js"],
    "env": {
      "LEADBREW_API_KEY": "lb_your_api_key_here",
      "LEADBREW_API_SECRET": "your_api_secret_here"
    }
  }
}
```

### Windsurf

Add to your Windsurf configuration:

```json
{
  "mcpServers": {
    "leadbrew": {
      "command": "node",
      "args": ["/path/to/leadbrew-mcp/dist/index.js"],
      "env": {
        "LEADBREW_API_KEY": "lb_your_api_key_here",
        "LEADBREW_API_SECRET": "your_api_secret_here"
      }
    }
  }
}
```

### Cline / Roo Code

Add to your VS Code settings:

```json
{
  "cline.mcpServers": {
    "leadbrew": {
      "command": "node",
      "args": ["/path/to/leadbrew-mcp/dist/index.js"],
      "env": {
        "LEADBREW_API_KEY": "lb_your_api_key_here",
        "LEADBREW_API_SECRET": "your_api_secret_here"
      }
    }
  }
}
```

### OpenAI Codex / ChatGPT

For OpenAI-based assistants, use the REST API directly. See [REST API examples](./examples/rest-api.md).

## Available Tools

| Tool | Description |
|------|-------------|
| `leadbrew_search_leads` | Search for leads by name, company, industry, position, country |
| `leadbrew_get_lead` | Get full lead details including emails and phone numbers |
| `leadbrew_search_companies` | Search for companies by name, industry, size |
| `leadbrew_get_company` | Get company details with employee list |
| `leadbrew_usage` | Check your API quota and usage statistics |

## Examples

### Finding Decision Makers

```
You: Find CTOs at fintech companies in New York

AI: [Searches using leadbrew_search_leads]

Found 156 leads matching your criteria:

**John Smith**
Position: Chief Technology Officer
Company: PayFlow Inc (Fintech)
Country: US
LinkedIn: https://linkedin.com/in/johnsmith
Lead ID: TGVhZGJyZXdtaWtlXzEyMzQ1

**Sarah Johnson**
Position: CTO
Company: BlockPay Solutions (Fintech)
Country: US
LinkedIn: https://linkedin.com/in/sarahjohnson
Lead ID: TGVhZGJyZXdtaWtlXzY3ODkw

... and 154 more results
```

### Getting Contact Information

```
You: Get the contact details for John Smith

AI: [Uses leadbrew_get_lead with the lead ID]

**John Smith**
Position: Chief Technology Officer
Company: PayFlow Inc (Fintech)
Country: US
LinkedIn: https://linkedin.com/in/johnsmith

Emails:
  - john.smith@payflow.com
  - jsmith@payflow.io

Phones:
  - +1 (555) 123-4567
```

### Building a Lead List

```
You: Find 10 marketing directors at SaaS companies with 50-200 employees

AI: [Searches with position="Marketing Director", industry="SaaS", min_size=50, max_size=200]

Found 89 leads. Here are the first 10:

1. **Emily Chen** - Marketing Director at CloudMetrics (Software/SaaS)
2. **Michael Brown** - Director of Marketing at DataSync Pro (SaaS)
3. **Jessica Williams** - Marketing Director at AppFlow Systems (SaaS)
...
```

### Researching Companies

```
You: Tell me about Stripe's team

AI: [Uses leadbrew_get_company with include_employees=true]

**Stripe**
Website: stripe.com
Industry: Financial Technology
Size: 8,000+ employees
LinkedIn: https://linkedin.com/company/stripe

Employees in database: 234

Sample employees:
  - Patrick Collison (CEO)
  - John Collison (President)
  - Claire Hughes Johnson (COO)
  - David Singleton (CTO)
  - Dhivya Suryadevara (CFO)
```

### Checking Your Quota

```
You: How many leads do I have left today?

AI: [Uses leadbrew_usage]

**LeadBrew API Usage**

Today's Usage:
  Leads used: 45/100
  Leads remaining: 55
  Requests made: 12

Last 7 Days:
  Total leads: 312
  Total requests: 89
```

## Tool Reference

### leadbrew_search_leads

Search for B2B leads with various filters.

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search query for lead name |
| `company` | string | Filter by company name |
| `industry` | string | Filter by industry |
| `position` | string | Filter by job title |
| `country` | string | Country code (US, UK, DE, etc.) |
| `limit` | number | Results per page (1-25) |
| `page` | number | Page number |

### leadbrew_get_lead

Get detailed information about a specific lead.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Lead ID from search results |

**Returns:** Full lead profile including emails and phone numbers.

### leadbrew_search_companies

Search for companies in the database.

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Company name search |
| `industry` | string | Filter by industry |
| `country` | string | Country code |
| `min_size` | number | Minimum employee count |
| `max_size` | number | Maximum employee count |
| `limit` | number | Results per page (1-25) |
| `page` | number | Page number |

### leadbrew_get_company

Get company details with optional employee list.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Company ID or LinkedIn handle |
| `include_employees` | boolean | No | Include employee list |

### leadbrew_usage

Check your API usage and quota.

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `days` | number | Days of history (1-90) |

## Rate Limits

| Limit | Value |
|-------|-------|
| Daily lead quota | 100 leads |
| Max per request | 25 leads |
| Company searches | Unlimited |
| Rate limit reset | Midnight UTC |

## REST API

You can also use the LeadBrew REST API directly:

```bash
curl -X GET "https://leadbrew.co/api/v1/leads?q=john&industry=Technology&limit=10" \
  -H "X-API-Key: lb_your_api_key" \
  -H "X-API-Secret: your_api_secret"
```

See [examples/rest-api.md](./examples/rest-api.md) for more REST API examples.

## Troubleshooting

### "API credentials not configured"

Make sure your environment variables are set correctly:
- `LEADBREW_API_KEY` should start with `lb_`
- `LEADBREW_API_SECRET` should be 64 characters

### "Rate limit exceeded"

You've used your daily quota of 100 leads. The limit resets at midnight UTC.

### "Invalid API credentials"

Check that:
1. Your API key is active (not revoked)
2. The key and secret match
3. No extra spaces in your configuration

## Support

- **Documentation:** [leadbrew.co/api-docs](https://leadbrew.co/api-docs)
- **Issues:** [GitHub Issues](https://github.com/FlatNineOrg/leadbrew-mcp/issues)
- **Email:** support@leadbrew.co

## License

MIT License - See [LICENSE](./LICENSE) for details.

---

<p align="center">
  Made with ❤️ by <a href="https://leadbrew.co">LeadBrew</a>
</p>