atum246/keelead

⚡ KeeLead

Find leads. Verify emails. Research companies. Close deals.

A free, open-source, self-hosted lead generation platform powered by AI with 62 data sources.

Features • Quick Start • Data Sources • Configuration • API Keys Guide • Docker • Architecture • Contributing

---

🆓 Why KeeLead?

---

✨ Features

🔍 62 Data Sources

• 35 FREE sources — No API key required, works out of the box!
• 27 premium sources — Optional API keys for enhanced data
• Categories: Search, Professional, Company, Local Business, Social Media, Developer, Startup, Government, Education, Email, Events

💬 AI Chat Interface

• ChatGPT/Claude-style natural language interface
• Ask: “Find me 50 SaaS founders in San Francisco”
• Multi-provider: OpenAI, Claude, Ollama, Groq, Mistral, NVIDIA, OpenRouter
• Streaming responses with markdown, tables, and code blocks

📧 10-Layer Email Verification

• Syntax validation (RFC 5322)
• Domain existence & MX record verification
• Disposable email detection (10K+ domain blocklist)
• SMTP verification, catch-all detection, spam trap detection
• Score 0-100 with detailed breakdown

🗺️ OpenStreetMap Local Business Search

• FREE worldwide coverage — no API key needed!
• Search: “restaurants in London”, “dentists in Tokyo”, “plumbers near Berlin”
• 40+ business type mappings
• Extracts: names, phones, emails, addresses, hours

🤖 Browser Automation

• Playwright-powered headless browser
• Scrape JavaScript-heavy sites
• Form filling, screenshots, infinite scroll
• Utility functions for tables, lists, cards

📊 Dashboard & Management

• 15+ pages with full dark theme
• Lead management with AI scoring (0-100)
• Kanban pipeline board
• Campaign management with drip sequences
• Analytics & reporting
• Export in 7 formats (CSV, JSON, Excel, vCard, PDF, XML, YAML)

🛡️ Compliance

• GDPR tools, CAN-SPAM compliance
• Do-Not-Contact list management
• Audit logs, consent management

---

🚀 Quick Start

# Clone the repository
git clone https://github.com/Atum246/keelead.git
cd keelead

# Install dependencies
npm install

# Set up database
npx prisma db push

# Seed with demo data (optional)
npx tsx prisma/seed.ts

# Start development server
npm run dev

Open http://localhost:3000 🎉

What Works Immediately (No API Keys!)

• ✅ 35 free data sources (OpenStreetMap, SEC EDGAR, GitHub, Reddit, etc.)
• ✅ Email verification (DNS, MX, SMTP checks)
• ✅ Full dashboard & lead management
• ✅ Export in 7 formats
• ✅ Compliance tools

What Needs API Keys

• 🤖 AI chat (at least one provider needed)
• 🔍 Premium search (Google, Bing, Brave)
• 📱 Social media (Twitter, Instagram, etc.)
• 💼 Premium data (Crunchbase, Hunter.io, etc.)

---

📦 Data Sources (62 Total)

✅ FREE Sources (35) — No API Key Required

🔍 Search (2)

💼 Professional (1)

🏢 Company (4)

📍 Local Business (4)

📱 Social (2)

👨‍💻 Developer (5)

🚀 Startup (2)

🏛️ Government (6)

🎓 Education (4)

📧 Email/Domain (3)

🎤 Events (1)

---

💰 Premium Sources (27) — API Keys Required

🔍 Search (3)

📱 Social Media (7)

💼 Professional (3)

🏢 Company (3)

📍 Local Business (5)

📧 Email (2)

🚀 Startup (3)

🎤 Events (3)

---

⚙️ Configuration

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

🤖 AI Providers (At Least One Required for Chat)

# OpenAI — Best overall quality
OPENAI_API_KEY=sk-...

# Anthropic Claude — Great for analysis
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter — Access to ALL models with one key
OPENROUTER_API_KEY=sk-or-...

# Ollama — FREE local AI (no API key!)
OLLAMA_BASE_URL=http://localhost:11434

# NVIDIA NIM — Free tier available
NVIDIA_API_KEY=nvapi-...

# Groq — Ultra-fast inference
GROQ_API_KEY=gsk_...

# Mistral — European AI
MISTRAL_API_KEY=...

🔍 Search APIs (Optional — Enhances Search Results)

GOOGLE_SEARCH_API_KEY=...
GOOGLE_SEARCH_CX=...
BING_SEARCH_API_KEY=...
BRAVE_SEARCH_API_KEY=...

📧 Email & Data Enrichment (Optional)

HUNTER_API_KEY=...
CLEARBIT_API_KEY=...

🔔 Notifications (Optional)

SLACK_WEBHOOK_URL=...
DISCORD_WEBHOOK_URL=...

---

🔑 API Keys Guide

Tier 1: Start Here (Free & Essential)

1. Ollama (FREE local AI)

   # Install Ollama
   curl -fsSL https://ollama.ai/install.sh | sh
   # Pull a model
   ollama pull llama3.1
   # KeeLead auto-detects it at http://localhost:11434
   

2. OpenRouter (Access to 100+ models, pay-as-you-go)

   • Go to openrouter.ai
   • Create account → Get API key
   • Add to .env: OPENROUTER_API_KEY=sk-or-...

Tier 2: Enhance Search (Optional)

3. Google Custom Search (100 free/day)

   • Go to console.cloud.google.com
   • Enable “Custom Search API”
   • Create API key
   • Go to programmablesearchengine.google.com
   • Create a search engine, get the CX ID
   • Add both to .env

4. Brave Search (2,000 free/month)

   • Go to api.search.brave.com
   • Create account → Get API key
   • Add to .env: BRAVE_SEARCH_API_KEY=...

Tier 3: Premium Data (Optional)

5. Hunter.io (25 free/month)

   • Go to hunter.io
   • Create account → Get API key
   • Add to .env: HUNTER_API_KEY=...

6. Yelp Fusion (5,000 free/day)

   • Go to fusion.yelp.com
   • Create app → Get API key
   • Add to .env: YELP_API_KEY=...

7. Google Maps ($200 free credit/month)

   • Go to console.cloud.google.com
   • Enable “Places API”
   • Create API key
   • Add to .env: GOOGLE_MAPS_API_KEY=...

---

🐳 Docker

Quick Start

docker-compose up -d

Manual Build

docker build -t keelead .
docker run -p 3000:3000 keelead

With Environment Variables

docker run -p 3000:3000 \
  -e OPENAI_API_KEY=sk-... \
  -e DATABASE_URL=file:./prisma/keelead.db \
  keelead

---

🏗️ Architecture

keelead/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── chat/          # AI chat endpoint
│   │   ├── leads/         # Lead CRUD
│   │   ├── verify/        # Email verification
│   │   ├── sources/       # Data source management
│   │   ├── export/        # Export endpoints
│   │   └── ...
│   ├── chat/              # Chat UI
│   └── dashboard/         # Dashboard pages
├── lib/
│   ├── sources/           # 62 data source plugins
│   │   ├── search/        # Search engines
│   │   ├── professional/  # LinkedIn, Crunchbase, etc.
│   │   ├── company/       # SEC EDGAR, OpenCorporates, etc.
│   │   ├── local/         # OpenStreetMap, Yelp, etc.
│   │   ├── social/        # GitHub, Reddit, etc.
│   │   ├── developer/     # NPM, PyPI, Stack Overflow, etc.
│   │   ├── startup/       # Indie Hackers, Beta List, etc.
│   │   ├── government/    # USASpending, Census, Patents, etc.
│   │   ├── education/     # Google Scholar, ORCID, etc.
│   │   ├── email/         # DNS, WHOIS, SSL, etc.
│   │   ├── events/        # Conference speakers, etc.
│   │   ├── base.ts        # Base source class
│   │   ├── types.ts       # Type definitions
│   │   └── index.ts       # Source manager
│   ├── browser/           # Playwright browser automation
│   │   ├── index.ts       # BrowserAutomation class
│   │   └── scraping-utils.ts
│   ├── ai/                # AI provider abstraction
│   ├── agent/             # AI agent & function calling
│   ├── email/             # Email verification engine
│   └── ...
├── prisma/                # Database schema
├── mcp/                   # MCP server
├── cli/                   # CLI tool
└── components/            # React components

Tech Stack

• Frontend: Next.js 14, React, TypeScript, Tailwind CSS
• Backend: Next.js API Routes, Prisma ORM
• Database: SQLite (easily switch to PostgreSQL)
• AI: Multi-provider (OpenAI, Claude, Ollama, Groq, etc.)
• Browser: Playwright for automation
• License: MIT

---

🤖 AI Agent Integration

MCP Server

KeeLead includes a built-in MCP (Model Context Protocol) server for AI agent integration.

# Start MCP server
npm run mcp

Function Calling

AI agents can use these tools:

• keelead_search_leads — Search across 62 data sources
• keelead_verify_email — 10-layer email verification
• keelead_research_company — Deep company research
• keelead_find_contact — Find contact information
• keelead_enrich_lead — Enrich lead data

---

📤 Export Formats

Export leads in 7 formats:

• CSV — Spreadsheet compatible
• JSON — Developer-friendly
• Excel (XLSX) — Microsoft Excel
• vCard — Contact import
• PDF — Reports & presentations
• XML — Enterprise integration
• YAML — Configuration-friendly

---

🛡️ Security

• All API keys stored encrypted
• Self-hosted — your data never leaves your server
• No telemetry or tracking
• GDPR & CAN-SPAM compliant tools
• Audit logging for all actions

---

🗺️ Roadmap

v2.0 ✅ (Current)

• [x] 62 data sources (35 free + 27 premium)
• [x] AI chat interface with multi-provider support
• [x] 10-layer email verification
• [x] OpenStreetMap local business search
• [x] Browser automation with Playwright
• [x] Dashboard with 15+ pages
• [x] Campaign management
• [x] Pipeline (Kanban)
• [x] Export in 7 formats
• [x] Compliance tools

v2.1 (Next)

• [ ] Browser extension (Chrome/Firefox)
• [ ] Real-time collaboration
• [ ] Voice interface (speech-to-text)
• [ ] Mobile app (React Native)
• [ ] CRM integrations (HubSpot, Salesforce)
• [ ] Webhook triggers
• [ ] Plugin marketplace

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Adding a New Data Source

1. Create a file in lib/sources/{category}/your-source.ts
2. Extend BaseSource class
3. Implement search(), optionally getCompany() and getContact()
4. Register in lib/sources/index.ts
5. Submit a PR!

---

📄 License

MIT License — see LICENSE

---

🙏 Acknowledgments

• Next.js — React framework
• Prisma — Database ORM
• Tailwind CSS — Styling
• OpenStreetMap — Free map data
• Playwright — Browser automation

---

Made with ⚡ by the KeeLead community