Leads Lord MCP

Local stdio MCP server for connecting Leads Lord to Claude Desktop, Codex, Cursor, local AI tools, and other MCP-compatible clients.

Leads Lord MCP is Agent Mode for Leads Lord. Your AI client does the reasoning. Leads Lord provides scoped lead data, research save-back, audit memo drafts, outreach drafts, lead scoring, live lead hunts, warmup guidance, and safety checks through your Leads Lord account.

Free-trial users can use MCP Agent Mode when they bring their own AI client or model key. External AI reasoning does not consume Leads Lord platform AI credits. Scraping, contact reveal, exports, high-volume sending, and other direct-cost or risky actions still follow account quotas and scopes.

Requirements

• Node.js 20.11+
• A Leads Lord API key from Settings -> API & MCP
• LEADS_LORD_API_URL, for example https://api.leads-lord.com

Recommended Setup

Use npx; no global install is required:

npx -y @leads-lord/mcp

Environment variables:

LEADS_LORD_API_KEY=ll_your_api_key_here
LEADS_LORD_API_URL=https://api.leads-lord.com

Claude Desktop

Add a custom MCP server to Claude Desktop, then restart Claude:

{
  "mcpServers": {
    "leads-lord": {
      "command": "npx",
      "args": ["-y", "@leads-lord/mcp"],
      "env": {
        "LEADS_LORD_API_KEY": "ll_your_api_key_here",
        "LEADS_LORD_API_URL": "https://api.leads-lord.com"
      }
    }
  }
}

Codex

Codex uses config.toml:

[mcp_servers.leads_lord]
command = "npx"
args = ["-y", "@leads-lord/mcp"]

[mcp_servers.leads_lord.env]
LEADS_LORD_API_KEY = "ll_your_api_key_here"
LEADS_LORD_API_URL = "https://api.leads-lord.com"

Cursor and Generic MCP Clients

Use a stdio server configuration:

{
  "name": "leads-lord",
  "command": "npx",
  "args": ["-y", "@leads-lord/mcp"],
  "env": {
    "LEADS_LORD_API_KEY": "ll_your_api_key_here",
    "LEADS_LORD_API_URL": "https://api.leads-lord.com"
  }
}

Local Development

LEADS_LORD_API_KEY="ll_your_dev_key_here" LEADS_LORD_API_URL="http://localhost:8080" node ./src/index.js

Tools

| Tool | Scope | Safety | | --- | --- | --- | | test_connection | API key | Read-only | | search_leads | read:leads | Read-only | | get_lead_details | read:leads, optional reveal:contacts | Sensitive | | start_lead_hunt | hunt:leads | Metered | | get_lead_hunt_status | hunt:leads | Read-only | | get_lead_hunt_results | read:leads | Read-only | | score_leads | score:leads | Analysis | | research_prepare_lead_research_brief | read:leads | Read-only | | research_save_external_findings | write:notes | Draft-only | | audit_memo_create_draft | write:audit_memos | Draft-only | | audit_memo_get | write:audit_memos | Read-only | | audit_memo_list_for_lead | write:audit_memos | Read-only | | lead_score_update | write:lead_scores | Draft-only | | outreach_create_email_draft | read:leads + write:outreach_drafts | Draft-only | | find_related_opportunities | read:leads | Analysis | | prepare_audit_context | generate:audit | Metered | | get_audit_status | generate:audit | Read-only | | create_campaign_draft | create:campaign_draft | Draft-only | | send_campaign_draft | send:email or send:whatsapp | High risk | | get_warmup_plan | read:crm | Read-only | | search_audience_contacts | read:audience | Sensitive |

search_leads supports smart expanded search. You can pass smart_search: false for exact search, or pass expanded_keywords and related_categories from your own AI client. MCP-provided terms are capped and forwarded to the Leads Lord API without spending Leads Lord AI credits for query expansion.

Safety Model

• API keys are scoped. Do not grant send scopes to untrusted AI clients.
• Contact reveal requires reveal:contacts or export:leads.
• Campaign send requires send:email or send:whatsapp and confirmSend=true.
• Agent Mode save-back tools such as research_save_external_findings, audit_memo_create_draft, lead_score_update, and outreach_create_email_draft do not call Leads Lord platform AI and do not send messages.
• Leads Lord backend still enforces plan limits, suppression checks, email warmup, daily caps, provider restrictions, and WhatsApp pacing/session checks.
• MCP is not unlimited scraping or sending. Your AI client provides reasoning, while Leads Lord platform actions still consume Leads Lord quotas and limits.

Example Prompts

• "Use Leads Lord to find 25 dental clinics in Toronto and score them for AI appointment automation."
• "Use Leads Lord MCP to get this lead's profile. Use your browser tools to inspect the website, then save an audit memo draft with evidence URLs. Do not send anything."
• "Use Leads Lord MCP to score these leads, save agent notes, and create draft-only outreach emails using my own AI client."
• "Generate a quick audit memo for this website and include 3 related opportunities."
• "Create a campaign draft for these 10 leads, but do not send anything."
• "Search Audience Intelligence for fitness creators in Dubai with verified emails, but exclude suppressed contacts."
• "Create a safe email warmup plan for this sender based on today's Leads Lord cap."

Troubleshooting

• LEADS_LORD_API_KEY is required: create/copy an API key from Settings -> API & MCP.
• Invalid or revoked API key: generate a new key or revoke stale client configs.
• Missing API key scope: edit the key scopes or create a new key with the needed permission.
• Cannot connect to API URL: verify LEADS_LORD_API_URL and network access.
• npx package not found: confirm @leads-lord/mcp is published, or run the local development command.
• Tool appears but returns permission error: the MCP client loaded correctly; the backend rejected the action by scope, plan, warmup, suppression, or safety rules.

Publishing Checklist

Do not publish automatically from an agent run. Before publishing:

npm install
npm run check
npm pack --dry-run
npm login
npm publish --access public

After publishing, test:

LEADS_LORD_API_KEY="ll_your_api_key_here" LEADS_LORD_API_URL="https://api.leads-lord.com" npx -y @leads-lord/mcp