LeadsClean MCP Server

An open-source MCP server that extracts structured B2B lead intelligence from company websites. Point it at any URL — get back a clean JSON object with company summary, buying signals, inferred needs, and personalised icebreaker lines.

Built as a reference implementation for MCP tool development. Demonstrates multi-provider LLM routing, dual-transport MCP serving, GDPR compliance patterns, and API key management — patterns you can reuse in your own MCP servers.

Works with Claude Desktop, Cursor, and any MCP-compatible client.

Tools

Output schema

{
  "company_name": "Acme Hotels Group",
  "core_business_summary": "Boutique hotel chain with 12 properties across Europe.",
  "product_category_match": "Strong match — hotel groups purchase furniture in bulk for room refits.",
  "recent_company_trigger": "Announced expansion to 3 new cities in Q1 2026, adding 400+ rooms.",
  "inferred_business_need": "Bulk furnishing for new hotel rooms on tight fit-out timelines.",
  "icebreaker_hook_business": "Running 12 properties across Europe is impressive — furnishing them at scale is where we help.",
  "icebreaker_hook_news": "Saw the Q1 expansion news — we help hotel groups source wholesale beds and sofas fast.",
  "data_provenance": {
    "source_url": "https://acmehotels.com",
    "source_type": "public_website",
    "collection_method": "jina_reader_public_fetch",
    "contains_pii": false,
    "gdpr_basis": "legitimate_interest",
    "gdpr_notes": "Extracted solely from publicly available company web pages. No personal data collected. Compliant with GDPR Art. 6(1)(f)."
  }
}

Every response includes data_provenance — a machine-readable GDPR metadata block indicating data source, PII status, and legal basis.

Quick start

Prerequisites

• Python 3.11+
• An API key for at least one supported LLM provider (see Environment variables below)

Install

pip install mcp-leadsclean

Or clone and install from source:

git clone https://github.com/edition/leadsclean
cd leadsclean
pip install -e .

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "leadsclean": {
      "command": "mcp-leadsclean",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Set the key for whichever provider(s) you use (see Environment variables).

Cursor

Add to your Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "leadsclean": {
      "command": "mcp-leadsclean",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

HTTP transport (production agent pipelines)

For remote agents or multi-tenant deployments, run with Streamable HTTP transport:

OPENAI_API_KEY=sk-... mcp-leadsclean --transport http --port 8001

The server exposes a single MCP endpoint at http://localhost:8001/mcp.

Demo mode

Try the server without an API key — useful for testing your agent pipeline or reviewing the output schema:

LEADSCLEAN_DEMO=1 mcp-leadsclean

All tool calls return a sanitised fixture response when LEADSCLEAN_DEMO=1 is set. The response includes "_demo": true so agents can detect and discard it.

Environment variables

The model parameter controls which provider is used. Provider is inferred from the model-name prefix — set the corresponding key:

The default model is gpt-4o-mini (OpenAI). To switch provider, pass the desired model ID in the tool call — e.g. claude-3-5-haiku-20241022 for Anthropic, qwen-turbo for Alibaba.

REST API

A standard FastAPI REST endpoint is also available for non-MCP integrations:

uvicorn main:app --reload

curl -X POST http://localhost:8000/extract-leads \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://acmecorp.com",
    "seller_context": "We provide cloud HR software to mid-size logistics companies."
  }'

Reusable patterns

This project demonstrates several patterns worth extracting for your own MCP servers:

Development

# Install dependencies
pip install -r requirements.txt

# Run MCP server (stdio)
python mcp_server.py

# Run MCP server (HTTP, port 8001)
python mcp_server.py --transport http

# Run REST API
uvicorn main:app --reload

How it works

1. Fetch — retrieves clean Markdown from the target URL via Jina Reader
2. Extract — passes the content to your chosen LLM (OpenAI, Anthropic Claude, Alibaba Qwen, or MiniMax) with a structured prompt
3. Return — outputs a JSON object matching the schema above

Content never leaves the pipeline: no data is stored by LeadsClean.

Built with Claude

This project was developed with the assistance of Claude by Anthropic — an AI assistant used for code generation, architecture design, and documentation.

License

MIT