# FlashLeads MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides AI tools access to FlashLeads lead generation capabilities. Use this to search for company leads directly from AI assistants like Claude Desktop.

## Features

- 🔍 **Web Harvest**: Search Google and collect company website leads with contact information
- 📊 **Lead Retrieval**: Get detailed company information including emails, phones, and social profiles
- ⚡ **Real-time Status**: Monitor your web harvest agent's progress
- 🔐 **Secure**: API key-based authentication
- 🚀 **Easy Setup**: Works with Claude Desktop and other MCP-compatible tools

## Quick Start (No Installation Required!)

### Step 1: Get Your API Key

Create an API key by calling the FlashLeads provisioning endpoint:

```bash
curl -X POST https://api.flashleads.io/api/provision/create-api-key \
  -H "Content-Type: application/json" \
  -d '{
    "secretKey": "choose-a-secure-password",
    "workspaceName": "My AI Workspace",
    "email": "you@email.com"
  }'
```

**Response:**
```json
{
  "success": true,
  "apiKey": "choose-a-secure-password",
  "workspaceId": "clx...",
  "credits": 1000,
  "message": "Workspace and API key created successfully"
}
```

💡 **Save your `apiKey` - you'll need it in the next step!**

### Step 2: Configure Claude Desktop

Edit your Claude Desktop config file:

- **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add this configuration (using **npx** - no installation needed!):

```json
{
  "mcpServers": {
    "flashleads": {
      "command": "npx",
      "args": [
        "-y",
        "@flashleads/mcp-server"
      ],
      "env": {
        "FLASHLEADS_API_KEY": "your-secret-key-from-step-1",
        "FLASHLEADS_API_URL": "https://api.flashleads.io"
      }
    }
  }
}
```

**Replace** `your-secret-key-from-step-1` with the `apiKey` you got in Step 1.

### Step 3: Restart Claude Desktop

1. Completely quit Claude Desktop (⌘Q on Mac, Alt+F4 on Windows)
2. Reopen Claude Desktop
3. Look for the 🔌 icon in the bottom right - "flashleads" should be connected!

### Step 4: Start Using It! 🎉

Now just chat with Claude naturally:

**Example prompts:**
- "Find me 20 coffee shop leads in Seattle"
- "Get restaurant contacts in Miami with email addresses"
- "Search for dental offices in Chicago"
- "Find plumbing companies in Los Angeles"

Claude will automatically use the FlashLeads tools to search and return real business leads with contact information!

---

## Alternative: Local Installation

If you prefer to install locally instead of using npx:

```bash
npm install -g @flashleads/mcp-server
```

Then use this config:

```json
{
  "mcpServers": {
    "flashleads": {
      "command": "flashleads-mcp",
      "env": {
        "FLASHLEADS_API_KEY": "your-secret-key",
        "FLASHLEADS_API_URL": "https://api.flashleads.io"
      }
    }
  }
}
```

---

## For Developers: Local Development

```bash
git clone https://github.com/yourusername/flashleads-mcp-server
cd flashleads-mcp-server
npm install
npm run build

# Configure with local path
{
  "command": "node",
  "args": ["/full/path/to/mcp-server/build/index.js"]
}
```

---

### Other MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client. See the [MCP documentation](https://modelcontextprotocol.io) for more details.

## Available Tools

### 1. run_web_harvest

Search Google and collect company website leads.

**Parameters:**
- `searchQuery` (required): What to search for (e.g., "restaurants", "coffee shops")
- `location` (required): Geographic location (e.g., "New York", "United States")
- `limit` (optional): Number of leads to collect (default: 10, max: 100)

**Example:**
```typescript
run_web_harvest({
  searchQuery: "coffee shops",
  location: "Seattle",
  limit: 20
})
```

### 2. get_web_harvest_leads

Retrieve leads collected by your web harvest agent.

**Parameters:**
- `status` (optional): Filter by status ("PENDING", "RUNNING", "COMPLETED", "FAILED")
- `limit` (optional): Max results to return (default: 50)

**Example:**
```typescript
get_web_harvest_leads({
  status: "COMPLETED",
  limit: 50
})
```

### 3. get_web_harvest_status

Check if your web harvest agent is running and see lead counts.

**Parameters:** None

**Example:**
```typescript
get_web_harvest_status()
```

## Usage Example

With Claude Desktop:

```
User: "Find me 30 restaurant leads in San Francisco"

Claude uses:
1. run_web_harvest({ searchQuery: "restaurants", location: "San Francisco", limit: 30 })
2. get_web_harvest_status() // Check progress
3. get_web_harvest_leads({ status: "COMPLETED" }) // Get results

Claude responds: "I found 30 restaurant leads in San Francisco:
1. Joe's Pizza - https://joespizza.com - (415) 555-0123 - joe@joespizza.com
2. ..."
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Development mode
npm run dev

# Test with MCP Inspector
npm run inspector
```

## Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `FLASHLEADS_API_KEY` | Your FlashLeads API key | - | Yes |
| `FLASHLEADS_API_URL` | API base URL | `http://localhost:5000` | No |

## Error Handling

The server provides detailed error messages for common issues:

- **Invalid API key**: Check your API key is correct
- **Rate limit exceeded**: Wait for the rate limit to reset (shown in error)
- **Agent already running**: Wait for current operation to complete
- **Missing parameters**: Check required parameters are provided

## Rate Limits

Default rate limits per API key:
- 100 requests per hour
- Rate limits reset hourly
- Contact support for higher limits

## Support

- 📧 Email: support@flashleads.io
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/flashleads-mcp-server/issues)
- 📖 Docs: [FlashLeads Documentation](https://docs.flashleads.io)

## License

MIT License - see [LICENSE](LICENSE) file for details

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.