FlashLeads MCP Server

# MCP Server Usage Examples Complete walkthrough of using FlashLeads MCP Server with Claude Desktop and other AI tools. ## Prerequisites 1. **FlashLeads Backend Running** ```bash cd bdr-node pnpm dev # Server running on http://localhost:5000 ``` 2. **Create Your API Key** ```bash curl -X POST http://localhost:5000/api/provision/create-api-key \ -H "Content-Type: application/json" \ -d '{ "secretKey": "mysecret123", "workspaceName": "My AI Agent Workspace", "email": "myai@example.com" }' ``` **Save the response - you'll need the `apiKey`!** --- ## Setup with Claude Desktop ### Step 1: Install MCP Server ```bash cd mcp-server npm install npm run build ``` ### Step 2: Get the Full Path ```bash pwd # Example output: /Users/username/Desktop/Github Projects /bdr-ai/mcp-server ``` ### Step 3: Configure Claude Desktop **MacOS**: Edit `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json` Add this configuration: ```json { "mcpServers": { "flashleads": { "command": "node", "args": [ "/Users/username/Desktop/Github Projects /bdr-ai/mcp-server/build/index.js" ], "env": { "FLASHLEADS_API_KEY": "mysecret123", "FLASHLEADS_API_URL": "http://localhost:5000" } } } } ``` **Important**: Replace the path and API key with your actual values! ### Step 4: Restart Claude Desktop 1. Completely quit Claude Desktop (Cmd+Q on Mac, Alt+F4 on Windows) 2. Reopen Claude Desktop 3. Look for the 🔌 icon in the bottom right corner 4. It should show "flashleads" as connected --- ## Usage Examples with Claude ### Example 1: Simple Lead Generation **You:** ``` Find me 10 coffee shop leads in Seattle ``` **What Claude Does Behind the Scenes:** 1. Calls `run_web_harvest` tool: ```json { "searchQuery": "coffee shops", "location": "Seattle", "limit": 10 } ``` 2. Waits a moment, then calls `get_web_harvest_status` to check progress 3. Once complete, calls `get_web_harvest_leads` with `status: "COMPLETED"` 4. Formats and presents the results to you **Claude's Response:** ``` I found 10 coffee shop leads in Seattle: 1. Seattle Coffee Works - Website: https://seattlecoffeeworks.com - Email: info@seattlecoffeeworks.com - Phone: +1-206-555-0123 - Address: 123 Pike St, Seattle, WA 98101 - LinkedIn: https://linkedin.com/company/seattlecoffeeworks 2. Espresso Vivace - Website: https://espressovivace.com - Email: contact@espressovivace.com - Phone: +1-206-555-0456 ... Would you like me to export these to a CSV file or search for more? ``` --- ### Example 2: Specific Industry Search **You:** ``` I need 25 Italian restaurant contacts in San Francisco ``` **Claude:** ``` I'll search for Italian restaurants in San Francisco for you. ``` **Claude calls:** ```json { "tool": "run_web_harvest", "arguments": { "searchQuery": "Italian restaurants", "location": "San Francisco", "limit": 25 } } ``` **Claude responds:** ``` I'm collecting Italian restaurant leads in San Francisco. I'll check back shortly... [After a few moments] Found 25 Italian restaurants in San Francisco! Here are the highlights: 1. Tony's Pizza Napoletana - Website: https://tonyspizzanapoletana.com - Phone: (415) 555-0100 - Email: info@tonyspizzanapoletana.com 2. A16 - Website: https://a16sf.com - Phone: (415) 555-0200 ... All 25 leads have been collected with contact information. Would you like me to filter by specific criteria or export the results? ``` --- ### Example 3: Check Status of Running Job **You:** ``` Is my web harvest still running? ``` **Claude calls:** ```json { "tool": "get_web_harvest_status" } ``` **Claude responds:** ``` Your web harvest agent status: - Status: RUNNING (Currently Running) - Total Leads: 15 - Completed Leads: 10 - Pending Leads: 5 - Failed Leads: 0 The agent is still collecting data. It's 66% complete. Should I check again in a moment? ``` --- ### Example 4: Get Only Completed Leads **You:** ``` Show me all the completed leads from my last search ``` **Claude calls:** ```json { "tool": "get_web_harvest_leads", "arguments": { "status": "COMPLETED", "limit": 50 } } ``` **Claude responds:** ``` Here are your 47 completed leads from the last web harvest: [Formatted list of all leads with complete details] Would you like me to: - Export these to CSV - Filter by specific criteria (has email, has phone, etc.) - Search for more leads in a different location ``` --- ### Example 5: Complex Multi-Step Task **You:** ``` I'm launching a food delivery app in Austin, Texas. Find me 30 restaurant leads with emails and phone numbers. Then summarize which ones have social media presence. ``` **Claude's Process:** 1. **Calls `run_web_harvest`:** ```json { "searchQuery": "restaurants", "location": "Austin, Texas", "limit": 30 } ``` 2. **Polls `get_web_harvest_status` until complete** 3. **Calls `get_web_harvest_leads`:** ```json { "status": "COMPLETED", "limit": 50 } ``` 4. **Analyzes the data and responds:** ``` I've collected 30 restaurant leads in Austin, Texas. Here's the summary: **Contact Information:** - 28 leads have phone numbers (93%) - 22 leads have emails (73%) **Social Media Presence:** - 25 with Instagram (83%) - 20 with Facebook (67%) - 15 with LinkedIn (50%) - 8 with Twitter/X (27%) **Top Leads with Full Contact Info + Social:** 1. Franklin Barbecue - Email: info@franklinbbq.com - Phone: (512) 555-0100 - Website: https://franklinbbq.com - Instagram: @franklinbbq (50K followers) - Facebook: /franklinbbq 2. Uchi Austin - Email: info@uchiaustin.com - Phone: (512) 555-0200 ... Would you like me to: - Focus on leads with email AND phone? - Export to a specific format? - Search for a specific cuisine type? ``` --- ## Advanced Usage ### Example 6: Iterative Refinement **Conversation Flow:** **You:** "Find restaurant leads in Miami" **Claude:** [Searches for 10 restaurants in Miami by default] **You:** "Great! Now find 50 more" **Claude:** [Calls `run_web_harvest` again with limit: 50, which updates the config and runs again] **You:** "Only show me the ones with emails" **Claude:** [Filters the results to show only leads with email addresses] **You:** "Export the top 20 to a table format" **Claude:** [Formats the top 20 leads with emails into a nice table] --- ### Example 7: Cross-Reference with Other Data **You:** ``` Find 20 coffee shop leads in Portland, then check if any of them are on LinkedIn ``` **Claude:** 1. Uses `run_web_harvest` to get coffee shops 2. Uses `get_web_harvest_leads` to retrieve results 3. Analyzes which ones have LinkedIn URLs 4. Presents filtered list with LinkedIn links --- ## MCP Server Logs The MCP server logs to stderr (won't interfere with Claude): ``` FlashLeads MCP Server running on stdio ``` To see detailed logs, you can check Claude's developer console or run the server in inspector mode: ```bash npm run inspector ``` --- ## Testing Without Claude You can test the MCP server directly using the MCP inspector: ```bash cd mcp-server npm run inspector ``` This opens a web interface where you can: - See all available tools - Test each tool with different parameters - View request/response data - Debug any issues --- ## Environment Variables Create a `.env` file in `mcp-server/`: ```bash FLASHLEADS_API_KEY=mysecret123 FLASHLEADS_API_URL=http://localhost:5000 ``` Or pass them via Claude Desktop config (as shown above). --- ## Troubleshooting ### "Tools not showing up in Claude" 1. Check the config path is correct: ```bash cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 2. Verify the MCP server path is correct: ```bash ls -la /path/to/mcp-server/build/index.js ``` 3. Restart Claude completely 4. Check for the 🔌 icon and that "flashleads" is listed ### "API key invalid" 1. Verify your API key is correct (use the exact secret you passed to `/api/provision/create-api-key`) 2. Test the API key directly: ```bash curl http://localhost:5000/api/provision/workspace-info \ -H "Authorization: Bearer mysecret123" ``` 3. Check the backend logs in the `bdr-node` terminal ### "Agent not running" 1. Check the backend `bdr-node` terminal - it should show: ``` SUBSCRIBED agent { id: '...', type: 'SERP', ... } ``` 2. Verify realtime is enabled on Supabase for the Agent table 3. Check the agent status: ```bash curl http://localhost:5000/api/mcp/web-harvest/status \ -H "Authorization: Bearer mysecret123" ``` --- ## What Can You Ask Claude? Here are more example prompts: - "Find 30 plumbing company leads in Los Angeles" - "Get me dental office contacts in Chicago with emails" - "Search for law firms in Boston and show me their LinkedIn profiles" - "Find software companies in Silicon Valley" - "Get me gym and fitness center leads in Denver" - "Check my web harvest status" - "Show me the last 20 leads you found" - "Find bakeries in Portland and tell me which ones have Instagram" --- ## Production Usage For production deployment: 1. **Update API URL** in Claude config: ```json "env": { "FLASHLEADS_API_KEY": "your-production-secret", "FLASHLEADS_API_URL": "https://api.flashleads.io" } ``` 2. **Use secure secrets** (longer keys in production) 3. **Monitor rate limits** - Default is 1000 req/hour --- ## Next Steps - Add more agent types (LinkedIn, Google Maps, YouTube) - Add webhook support for long-running jobs - Create a web dashboard to manage API keys - Publish to npm: `@flashleads/mcp-server` --- **Need Help?** - Check the README.md for full documentation - Email: support@flashleads.io - GitHub Issues: [Report a bug](https://github.com/yourusername/flashleads-mcp-server/issues)