FlashLeads MCP Server

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