CleanLeads CLI & MCP

Install

Requires Node.js 18 or newer.

npm install -g cleanleads

# or run one-off without installing
npx cleanleads --help

Login (device code)

Run cleanleads login. You will see an 8-character code and your browser will open the authorization page with the code pre-filled:

cleanleads login

To authorize this device:
  1. Open  https://www.cleanleadsai.com/cli-auth
  2. Enter code:  9KES-NH4Y

Enter the code on the page (sign in first if asked) and click Authorize CLI. The CLI receives its own dedicated API key automatically — the key is never displayed on screen.

Every login creates a separate key just for that device. Your existing API key, webhooks, and integrations keep working. If your browser did not open, go to cleanleadsai.com/cli-auth manually and type the code from your terminal.

Prefer to paste a key directly? Use cleanleads login --key cl_your_key_here, or set the CLEANLEADS_API_KEY environment variable.

Commands

# Account and billing
cleanleads account
cleanleads credits 20

# Business search (free) — save results as a list
cleanleads search-businesses "managed service providers" "Austin, TX" --limit 10
cleanleads search-businesses dentists "Austin, TX" --save "Austin Dentists"

# People search (charged per person found)
cleanleads search-people --preset decision-makers --industry msp \
  --location "Charlotte, NC" --limit 5

# People at a known company
cleanleads find-people acme.com --departments executive,sales --limit 5

# Emails
cleanleads domain-emails acme.com
cleanleads find-email Jane Doe acme.com
cleanleads linkedin-email https://www.linkedin.com/in/janedoe

# Enrichment (standard = email, premium = email + phone)
cleanleads enrich --first Jane --last Doe --company Acme --website acme.com
cleanleads enrich --premium --first Jane --last Doe --company Acme

# Validation
cleanleads validate email jane@acme.com
cleanleads validate phone "+1 512 555 0100"

# Saved data
cleanleads lists
cleanleads contacts --has-email --status ENRICHED --limit 20
cleanleads company-intel acme.com

Use with AI agents (MCP)

Two ways to give AI agents access to these tools.

Hosted remote MCP (recommended)

Point any MCP-compatible client at:

URL:     https://www.cleanleadsai.com/api/mcp
Header:  X-API-Key: YOUR_API_KEY

Local stdio MCP via this CLI

For desktop clients such as Claude Desktop, add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "cleanleads": {
      "command": "npx",
      "args": ["-y", "cleanleads", "mcp"],
      "env": { "CLEANLEADS_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Both expose the identical tool set; each call is billed to the authenticated account’s credits.

Managing device keys

Every CLI login and MCP connection gets its own key, so revoking one never breaks the others. See all active keys and revoke any of them in Settings → Security. Keys are labeled by device and show when they were last used.

Billing notes

• Business/local search is free.
• Email finds, people search, and enrichment consume credits per record.
• Explore with small limits (--limit 5) before scaling up.
• Current credit costs are listed in the API tool catalogue.