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": "you@email.com"
}'
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
- Completely quit Claude Desktop (⌘Q on Mac, Alt+F4 on Windows)
- Reopen Claude Desktop
- 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 - joe@joespizza.com
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: support@flashleads.io
- 🐛 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.