AI Workflow Lead Generation System

A configurable, agentic lead generation system showcasing XPOZ MCP + Claude Code capabilities.

This system autonomously finds and analyzes potential customers for AI workflow automation products by searching Twitter for users expressing buying intent, pain points, and competitor frustrations.

---

🚀 Quick Start

Prerequisites:

• Claude Code CLI with XPOZ MCP server configured
• Python 3.8+ with pandas and numpy (pip install -r requirements.txt)

Run the workflow:

Execute the workflow in config/workflow_instructions.md

Claude will autonomously:

1. Read configuration files to understand search parameters
2. Execute XPOZ searches across multiple strategies
3. Download and process complete datasets
4. Generate Python code to score and filter leads
5. Perform deep LLM analysis on top candidates
6. Export ranked leads with actionable insights

Output: output/leads_YYYY-MM-DD.csv with 50 ranked leads

---

📁 Project Structure

ai-workflow-lead-gen/
├── config/                          # All customization happens here
│   ├── workflow_instructions.md     # Step-by-step workflow for Claude
│   ├── search_config.yaml           # Search strategies, keywords, filters
│   ├── analysis_prompt.txt          # LLM analysis criteria
│   └── output_template.yaml         # Output CSV structure
│
├── temp/                            # Runtime files (created during execution)
├── output/                          # Final CSV exports
├── requirements.txt                 # Python dependencies
└── README.md

Key design principle: All logic is in configuration files. Claude reads these at runtime and executes autonomously - no hardcoded scripts.

---

🎯 What This System Showcases

XPOZ MCP Capabilities

Keyword Search with Aggregations:

• getTwitterUsersByKeywords - Boolean OR queries across multiple keywords
• Built-in aggregation fields: relevantTweetsCount, relevantTweetsLikesSum, relevantTweetsImpressionsSum
• 60-day rolling date windows for recency filtering

Complete Dataset Export:

• dataDumpExportOperationId - CSV export handling thousands of rows efficiently
• Async operation pattern with checkOperationStatus polling
• Direct S3 download URLs with redirect handling

Deep User Analysis:

• getTwitterPostsByAuthor - Retrieve full tweet history for specific users
• Multi-field data extraction (text, engagement, dates)
• Parallel operation execution for performance

Multi-Strategy Search:

• Execute multiple independent searches with different keyword sets
• Combine and deduplicate results across strategies
• Tag leads by discovery method for attribution

Claude Code Intelligence

Agentic Orchestration:

• Reads markdown, YAML, and text configuration files
• Interprets instructions and executes multi-step workflows autonomously
• Makes decisions based on data patterns

Hybrid Analysis:

• Generates Python code on-the-fly for quantitative scoring
• Performs qualitative LLM analysis of tweet content
• Combines structured data (XPOZ) with unstructured insights (tweets)

Tool Coordination:

• Manages complex MCP tool sequences (search → poll → export → download)
• Executes parallel operations for efficiency
• Handles async patterns and retries

Pattern Recognition:

• Detects content creators vs genuine buyers
• Identifies urgency signals in natural language
• Extracts specific pain points from conversational text
• Suggests search optimization based on results

Professional Workflow Design

• Config-driven: Easy to customize without code changes
• Transparent: CSV pipeline is inspectable at every step
• Reproducible: Dated outputs create audit trail
• Modular: Each phase (search, score, analyze, export) is independent
• Self-documenting: Claude explains its process as it works

---

📊 Output Format

output/leads_YYYY-MM-DD.csv contains up to 50 ranked leads with:

Column	Description
rank	Lead ranking (1 = highest score)
username	Twitter username
profile_url	Direct link to Twitter profile
lead_score	Overall score (0-100) from quantitative metrics
intent_score	LLM-assessed buying intent (1-10)
urgency_score	LLM-assessed urgency level (1-10)
sentiment	frustrated / curious / excited
pain_points	Specific problems extracted from tweets
why_good_lead	LLM explanation of lead quality
recommended_approach	Tailored outreach strategy
followers	Follower count
relevant_posts	Times they posted about topic
engagement_rate	Average engagement per relevant post
bio	Profile description
location	User location
last_relevant_post	Most recent relevant post date
found_via	Which search strategy found them

---

⚙️ Customization

Search Strategies

Edit config/search_config.yaml to modify:

Keywords:

query_keywords:
  - "your keyword phrase here"
  - "another search term"

Date Range:

date_range:
  days_back: 60  # Adjust lookback window

Filters:

filters:
  min_relevant_posts: 1      # Minimum posts about topic
  min_lead_score: 35         # Score threshold (0-100)

Analysis Depth:

output:
  top_leads_to_analyze: 10   # How many get deep LLM analysis
  max_export: 50             # Total leads in final CSV

Analysis Criteria

Edit config/analysis_prompt.txt to change how Claude evaluates tweets:

• Intent scoring guidelines (1-10 scale)
• Urgency detection signals
• Sentiment classification rules
• Content creator vs buyer detection
• Recommended approach templates

Output Structure

Edit config/output_template.yaml to:

• Add/remove CSV columns
• Change column ordering
• Modify calculated fields
• Adjust sorting logic

---

🔬 Technical Implementation

Scoring Algorithm

Leads are scored quantitatively (0-100 points) using XPOZ aggregation data:

• Intent (0-50 pts): relevantTweetsCount × 12 (capped at 50)

  • More posts = stronger signal of genuine interest

• Recency (0-40 pts): Days since last relevant post

  • ≤7 days = 40 pts
  • ≤14 days = 30 pts
  • ≤21 days = 20 pts
  • ≤30 days = 10 pts

  • 30 days = 0 pts

• Engagement (0-10 pts): (avg_likes / followers) × 100 × 2 (capped at 10)

  • Basic quality filter to detect spam/bots

LLM analysis adds qualitative scores (1-10 scale) for intent and urgency based on actual tweet content.

Content Creator Detection

The system distinguishes between:

Content Creators (filtered out):

• Post lists/threads: "120 AI tools", "10 ways to..."
• Promotional language: "Follow for more", "RT if you agree"
• High posting frequency (multiple times per day)
• Educational content aimed at followers

Genuine Buyers (prioritized):

• Ask questions about their own workflow
• Complain about specific tasks in their business
• Seek recommendations for their use case
• Post infrequently (1-3 times = real problem)

Search Strategy Design

Three complementary approaches:

1. buyer_intent - Active buying signals

   • "need workflow automation"
   • "looking for AI agents"
   • "evaluating automation tools"

2. pain_points - Automation-specific frustrations

   • "automate data entry"
   • "manual workflow bottleneck"
   • "tired of manual processes"

3. competitor_frustration - Dissatisfaction with existing tools

   • "Zapier too expensive"
   • "Make.com alternative"
   • "frustrated with Power Automate"

Each strategy uses meaningful phrases (not just brand names) to pre-filter at the search level.

Execution Pattern

1. Parallel Search: All 3 strategies execute simultaneously
2. CSV Export: Full datasets downloaded via dataDumpExportOperationId
3. Python Processing: Claude generates scoring script at runtime
4. Parallel Deep Dive: Top 10 users analyzed in parallel
5. LLM Analysis: Claude reads actual tweets and extracts insights
6. Structured Export: Results mapped to template and sorted by score

---

🔄 Usage Patterns

One-time execution:

Execute the workflow in config/workflow_instructions.md

Scheduled execution:

• Add cron job or scheduled task
• Always searches 60-day rolling window from today
• Exports with current date automatically

Iterative refinement:

1. Run workflow and review output/leads_YYYY-MM-DD.csv
2. Check "Market Insights" section of Claude's summary
3. Add suggested keywords to config/search_config.yaml
4. Adjust filters if too many/few leads
5. Re-run

---

📈 Typical Results

• Total users found: 150-400 across 3 strategies
• Qualified leads: 50-100 after scoring and filtering
• Deep analysis: Top 10 with LLM insights
• Execution time: 5-10 minutes
• Output: 50 leads ranked by score

Example top lead:

@john_startup (Score: 87.5)
Intent: 9/10 | Urgency: 8/10 | Sentiment: Frustrated
Pain: "Spending 15+ hours/week on manual invoice processing"
Why good lead: Founder actively seeking automation, quantified pain
Approach: ROI calculator showing time savings, respond within 24h

---

🛠️ Troubleshooting

"No XPOZ MCP connected"

• Ensure XPOZ MCP server is configured in your Claude Code settings

"No results found"

• Verify keywords match actual Twitter discussions
• Broaden search by reducing min_lead_score threshold
• Extend days_back to increase time window

"CSV download failed"

• Check internet connectivity
• XPOZ may still be processing - wait 30s and retry
• Ensure curl -L flag is used (follows redirects)

"Low quality leads (content creators)"

• Review keywords - avoid generic terms like "AI tools"
• Use specific problem phrases: "automate X" vs "automation"
• Adjust LLM analysis criteria in config/analysis_prompt.txt

---

🧩 Extending the System

Add new search strategies:

- name: "new_strategy"
  description: "Your description"
  tool: "mcp__xpoz__getTwitterUsersByKeywords"
  query_keywords:
    - "keyword 1"
    - "keyword 2"
  query_operator: "OR"
  fields: [username, name, followersCount, relevantTweetsCount, ...]

Modify scoring weights: Edit Step 3 instructions in config/workflow_instructions.md to adjust point allocations.

Change analysis depth: Increase/decrease top_leads_to_analyze in config/search_config.yaml.

Add export fields: Add columns to config/output_template.yaml with source mappings.

Integrate with CRM: Add Step 8 to config/workflow_instructions.md with API calls to your CRM.

---

📄 License

Demo project for showcasing XPOZ MCP + Claude Code capabilities.

---

Built with XPOZ MCP and Claude Code 🚀