FlashLeads MCP Server

A Model Context Protocol (MCP) 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:

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": "[email protected]"
  }'

Response:

{
  "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!):

{
  "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:

npm install -g @flashleads/mcp-server

Then use this config:

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

For Developers: Local Development

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 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:

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:

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:

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 - [email protected]
2. ..."

Development

# 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: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: FlashLeads Documentation

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please read our Contributing Guide first.

Changelog

See CHANGELOG.md for release history.