LeadIntel

Free, open-source, local-first Model Context Protocol (MCP) server and Python library for AI-powered business intelligence and B2B lead generation.

LeadIntel empowers AI assistants — such as Claude Desktop, Google Antigravity, and other MCP-compatible clients — to discover businesses, audit websites, benchmark competitors, evaluate deterministic lead scores, run local AI strategic insights via Ollama, export publication-grade multi-sheet Excel spreadsheets, and generate executive business intelligence reports.

---

Core Principles

• 100% Free & Open-Source: Licensed under the permissive MIT License.
• Local-First Architecture: No mandatory paid APIs, no mandatory API keys, no billing accounts, and no subscriptions.
• Deterministic Lead Scoring: Transparent, evidence-based scoring models (0–100) that distinguish verified gaps from unavailable information without arbitrary penalties.
• Strict Privacy: Zero telemetry, zero cloud AI exfiltration. Optional AI uses local Ollama instances (http://localhost:11434).
• Ethical & Compliant: Adheres to OpenStreetMap ODbL 1.0 licensing, respects website robots.txt rules, prevents private personal data harvesting, and provides comprehensive SSRF and path traversal protections.

---

Architecture

LeadIntel is structured into clean, decoupled layers:

graph TD
    Client["MCP Clients (Claude Desktop / Antigravity / Cursor)"] --> MCP["LeadIntel MCP Server (stdio transport)"]

    subgraph "LeadIntel Tools (14 Registered MCP Tools)"
        T1["search_businesses"]
        T2["get_business_details"]
        T3["find_business_website"]
        T4["analyze_website"]
        T5["check_seo"]
        T6["find_social_profiles"]
        T7["find_competitors"]
        T8["compare_businesses"]
        T9["score_lead"]
        T10["generate_business_insights"]
        T11["generate_outreach"]
        T12["generate_business_report"]
        T13["export_leads"]
        T14["get_saved_leads"]
    end

    MCP --> T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9 & T10 & T11 & T12 & T13 & T14

    subgraph "Core Services & Providers"
        P_OSM["OpenStreetMap / Overpass Provider"]
        P_Demo["Offline Demo Provider"]
        S_Web["Website Analyzer & Robots Checker"]
        S_SEO["Custom 0-100 SEO Auditor"]
        S_Social["Social Media Profile Extractor"]
        S_Comp["Competitor Taxonomy & Benchmarking Engine"]
        S_Score["Deterministic 100-pt Lead Scoring Engine"]
        S_Ollama["Local AI Service (Ollama HTTP Client)"]
        S_Export["OpenPyXL Multi-Sheet Excel & CSV Exporter"]
        S_Report["Executive Report Generator (MD / HTML / JSON)"]
        S_DB["Local SQLite Persistence (.leadintel.db)"]
    end

    T1 & T2 & T3 --> P_OSM & P_Demo
    T4 & T5 & T6 --> S_Web & S_SEO & S_Social
    T7 & T8 --> S_Comp
    T9 --> S_Score
    T10 & T11 --> S_Ollama
    T12 --> S_Report
    T13 --> S_Export
    T1 & T14 --> S_DB

---

Registered MCP Tools

LeadIntel provides 14 registered MCP tools:

#	Tool Name	Description	Key Inputs
1	search_businesses	Discover local businesses, identify website opportunities, calculate distance, and prioritize leads	query, location, category, limit, latitude, longitude, radius_meters, sort_by, research_websites, wider_metro
2	get_business_details	Retrieve full coordinates, address, and contact details for a specific business	business_id
3	find_business_website	Discover and verify official websites using search heuristics and OSM tags	business_name, location, category
4	analyze_website	Audit web availability, HTTPS, SSL validity, viewport, headings, and broken links	url, check_broken_links
5	check_seo	Deterministic 100-point on-page SEO audit (titles, metas, H1s, alt tags, robots.txt, sitemaps)	url
6	find_social_profiles	Extract verified official profiles (LinkedIn, X/Twitter, Facebook, Instagram, YouTube, Pinterest)	url
7	find_competitors	Discover geographically and categorically relevant industry competitors	business_name, business_category, city, state
8	compare_businesses	Side-by-side benchmark comparison between target business and industry rivals	target_business, competitors
9	score_lead	Deterministic 100-point lead qualification assessing website quality, SEO, social, and mobile gaps	business_name, website_analysis, seo_audit, social_profiles
10	generate_business_insights	Local AI business analysis, opportunity explanations, and service recommendations via Ollama	business_name, lead_score_data, website_analysis
11	generate_outreach	Local AI multi-channel outreach pitches (Cold Email, LinkedIn connection, WhatsApp message)	business_name, service_focus, contact_name
12	generate_business_report	Multi-format executive intelligence report (Markdown, styled HTML, or JSON) across 12 sections	business_info, lead_score_data, output_format
13	export_leads	Search and export leads to multi-sheet formatted Excel (.xlsx), CSV, or JSON	query, location, format, output_path
14	get_saved_leads	Retrieve and filter previously researched businesses from the local database	min_opportunity_score, limit

---

Website Opportunity Intelligence (v0.2.0 - v0.3.0)

LeadIntel is specifically engineered for digital marketing agencies, SEO professionals, and web developers seeking high-probability web development and redesign clients.

1. Website Status Lifecycle

Every discovered business receives an explicit, deterministic website_status:

• website_verified: Official company website confirmed active, accessible, and owned by the entity.
• website_not_found_after_research: Missing from OpenStreetMap and confirmed absent after secondary web research across search engines and directory listings.
• website_broken: Website URL exists but returns HTTP 4xx/5xx errors or network timeouts.
• website_unverified: Discovered domain name does not match the business identity.
• website_not_checked: OpenStreetMap website field was empty and web research was not requested.

2. Deterministic Opportunity Scoring & Tech Stack Detection

website_opportunity_score (0–100) deterministically ranks web agency outreach leverage:

1. No website found after research: 90–100 (default: 95.0) — Highest priority new-build prospects.
2. Broken websites: 75–89 (default: 80.0) — Urgent repair / redesign prospects.
3. Weak / outdated websites: 50–74 (default: 65.0) — Missing mobile viewport or modern SSL security.
4. Significant SEO deficiencies: 30–49 (default: 40.0) — Missing meta descriptions, title tags, or slow response times.
5. Modern, established websites: 5–29 (default: 15.0) — Fast, mobile-ready, HTTPS-secured.

• Tech Stack & Contact Surface detection: Automated HTML footprint analysis detects underlying CMS platforms (WordPress, Shopify, Wix, Squarespace) and verifies whether direct contact routes (<a href="..."> with contact, about, or mailto:) exist.

3. Geographic Precision & Distance

• Spherical Haversine calculation: Every lead includes exact distance_meters and distance_km from the search centre.
• Strict radius enforcement: Rejects distant municipalities (e.g. Alandi or PCMC when searching Pune city center).
• Urban core vs. wider metro: Standard 6 km urban core radius, with optional wider_metro=True (25 km) for full metropolitan exploration.
• Road & infrastructure rejection: Rejects highway ways, bus platforms, and non-commercial geographic objects.

4. Local Storage

Researched businesses from search_businesses are automatically persisted to a local .leadintel.db SQLite database using upsert semantics. This preserves historical search intelligence across MCP sessions, speeds up pipeline reviews, and prevents redundant external API and scraping calls. Stored leads can be queried directly at any time using the get_saved_leads tool.

---

Requirements

• Python: 3.11 or newer
• uv: Modern, high-speed Python package manager (install uv)
• Operating System: macOS, Linux, or Windows
• (Optional) Ollama: Locally installed Ollama for local AI features

---

Installation

# 1. Clone the repository
git clone https://github.com/example/leadintel.git
cd leadintel

# 2. Sync dependencies using uv
uv sync

# 3. Create environment configuration (optional)
cp .env.example .env

---

MCP Client Configuration

Claude Desktop Setup

Add LeadIntel to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "leadintel": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/leadintel",
        "run", "leadintel-server"
      ]
    }
  }
}

Google Antigravity Setup

Add LeadIntel to your Antigravity project configuration:

{
  "mcpServers": {
    "leadintel": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/leadintel",
        "run", "leadintel-server"
      ],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

---

Optional Local AI Setup (Ollama)

LeadIntel includes zero-cost, local AI capabilities via Ollama:

# 1. Install and start Ollama
ollama serve

# 2. Pull a recommended lightweight model
ollama pull llama3

# 3. Enable in .env
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

Privacy Guarantee: All prompts are sent exclusively to your local loopback interface (http://localhost:11434). No business data or prompt information is sent to third-party cloud providers.

---

Usage Examples

1. Discover Businesses & Export to Multi-Sheet Excel

Ask your AI assistant:

"Search for dental clinics in Austin, TX and export them to an Excel workbook."

Or invoke the tool directly:

await mcp.call_tool("export_leads", {
    "query": "dental clinic",
    "location": "Austin, TX",
    "format": "excel",
    "limit": 20
})

The resulting Excel workbook includes 7 dedicated worksheets:

1. Dashboard Summary: Aggregate KPI cards, lead priority distribution, and industry mix.
2. Business Leads: Address, contact information, phone, email, website, and data attribution.
3. Website Audit: Availability, HTTPS status, load time, mobile viewport, and contact forms.
4. Competitor Intelligence: Local competitors, category specialization, and confidence metrics.
5. Lead Scoring: Overall 100-pt score, priority tier, and evidence completeness percentage.
6. AI Insights: Executive summaries and strategic service opportunities.
7. Outreach: Multi-channel draft templates for emails, LinkedIn, and WhatsApp.

2. Website & SEO Diagnostic Audit

"Audit the website and technical SEO health for https://example.com."

# Analyze technical performance and structure
website_data = await mcp.call_tool("analyze_website", {"url": "https://example.com"})

# Perform 0-100 technical SEO evaluation
seo_data = await mcp.call_tool("check_seo", {"url": "https://example.com"})

3. Generate Executive Business Intelligence Report

"Create a comprehensive business research report for Apex Solar in Denver, CO in HTML format."

report_html = await mcp.call_tool("generate_business_report", {
    "business_info": {
        "name": "Apex Solar Solutions",
        "category": "Solar Energy Equipment",
        "city": "Denver",
        "state": "CO",
        "website": "https://apexsolar.example"
    },
    "output_format": "html"
})

---

Screenshots Placeholder

+--------------------------------------------------------------------------+
|                       LeadIntel Dashboard (Excel Export)                 |
+--------------------------------------------------------------------------+
|  Total Businesses: 50  |  High Priority: 14  |  Avg Lead Score: 72/100   |
+--------------------------------------------------------------------------+
|  [Sheet 1: Dashboard] [Sheet 2: Leads] [Sheet 3: Website Audit] ...      |
+--------------------------------------------------------------------------+
|  (Interactive screenshots will be published with the v0.1 release)       |
+--------------------------------------------------------------------------+

---

Security & Ethical Safeguards

• SSRF & DNS Rebinding Mitigation: Strict validation against loopback, private subnets (RFC 1918), carrier-grade NAT (RFC 6598), and cloud instance metadata (169.254.169.254, fd00:ec2::254, metadata.google.internal). All HTTP redirects are validated before being followed.
• Path Traversal Protection: Export file paths are sanitized against traversal sequences (..), null bytes, and sensitive system directories (/etc, /usr, ~/.ssh).
• Spreadsheet Formula Injection Prevention: Cell contents starting with =, +, -, @, \t, or \r are sanitized with leading text escapes.
• HTML Injection Defense: Stored XSS defense using strict entity escaping across all dynamic fields in HTML executive reports.
• ODbL License Attribution: Data retrieved from OpenStreetMap contributors is attributed in accordance with the Open Database License.

---

Limitations

• Search Coverage: Business discovery relies on OpenStreetMap and Nominatim data, which may vary in coverage density depending on geographic region and country.
• On-Page Technical SEO: The check_seo tool evaluates on-page technical factors and source standards. It does not replicate proprietary search engine ranking algorithms or backlinks.
• Deterministic Lead Scoring: Lead scores evaluate observable digital presence gaps to identify service opportunities. They do not predict commercial budget or purchasing authority.

---

License

LeadIntel is free and open-source software licensed under the MIT License. OpenStreetMap data is © OpenStreetMap contributors licensed under the Open Database License (ODbL 1.0).