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.

• 🔍 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

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!

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.

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!

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!

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"
      }
    }
  }
}

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"]
}

The server uses stdio transport and can be integrated with any MCP-compatible client. See the MCP documentation for more details.

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
})

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
})

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

Parameters: None

Example:

get_web_harvest_status()

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. ..."

# 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

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

Default rate limits per API key:

• 100 requests per hour
• Rate limits reset hourly
• Contact support for higher limits

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: FlashLeads Documentation

MIT License - see LICENSE file for details

Contributions are welcome! Please read our Contributing Guide first.

See CHANGELOG.md for release history.