How do I use smartleadai-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@smartleadai-mcp Find me 50 leads for SaaS companies in the USA" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

smartleadai-mcp

by voriq-ai

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

smartleadai-mcp

Unofficial MCP integration for Smartlead. This project is not affiliated with, endorsed by, or sponsored by Smartlead.ai.

A Model Context Protocol server for the Smartlead API, with complete SmartProspect coverage, for MCP-capable agents and clients.

183 safety-reviewed tools across all four Smartlead API hosts. The official reference cannot be represented honestly as a simple tool-count ratio: it has duplicate pages, and one page combines four different API-key methods. Unsafe, duplicate, financially consequential, and undocumented operations are excluded with recorded reasons — see docs/endpoint-coverage.md.

That includes all 26 documented SmartProspect endpoints, the prospecting product other Smartlead MCP servers omit entirely.

Everything is built from Smartlead's public official documentation. Exposed routes, methods, parameters, corrections, and known documentation gaps are listed in docs/endpoint-coverage.md.

Related MCP server: SmartLead MCP Server

Why this exists

Smartlead's SmartProspect family lives on a different API host from the rest of the Smartlead API, and its most useful operations spend prospecting credits. Existing third-party tooling either omits SmartProspect entirely or targets routes that are not in Smartlead's current API reference (for example POST /api/v1/verify-emails, which returns 404 Cannot POST /api/v1/verify-emails). This package:

talks to all four documented Smartlead hosts, correctly and separately;
never implements an undocumented route — there is no verify_emails tool here;
treats credit spend as a privileged action that requires two independent approvals before any HTTP request is made;
returns structured JSON envelopes instead of prose, so an agent can branch on the result.

Requirements

Node.js 20.19 or newer. CI runs the full verification suite on 20.19 (the declared floor) and 22 on every push.
A Smartlead API key with SmartProspect access.

Installation

Run it directly with npx (no install step):

SMARTLEAD_API_KEY=sl_your_key npx -y smartleadai-mcp

Or install it and use the smartleadai-mcp bin:

npm install -g smartleadai-mcp
SMARTLEAD_API_KEY=sl_your_key smartleadai-mcp

The server speaks MCP over stdio. Started by hand it will simply wait for a client on stdin; that is expected.

Command line

The same binary is an MCP server when run with no arguments, and a small helper CLI when given a subcommand.

smartleadai-mcp init       # interactive setup: verify the key, print client config
smartleadai-mcp doctor     # check configuration and validate the key
smartleadai-mcp config     # print effective configuration (credential redacted)
smartleadai-mcp tools      # list tools with their safety classification
smartleadai-mcp help

Start here:

npx -y smartleadai-mcp init

init verifies the key, asks which safety mode you want, then prints ready-to-paste config for Claude Desktop, Claude Code and Hermes. It offers to write a local .env (mode 0600) but never overwrites an existing key.

doctor diagnoses a broken setup:

✓ configuration  valid
  key            <configured; hidden>
  mode           readonly  (default — no writes, no credit spend)
  credit spend   disabled
✓ api key        accepted by Smartlead
✓ tools          183 registered

Both validate the key against GET /countries?limit=1 — free, read-only, and touching no contact data, so diagnosing a setup can never spend credits or pull a prospect record. The CLI never prints any character from the configured key.

Client configuration

Claude Desktop

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

{
  "mcpServers": {
    "smartlead": {
      "command": "npx",
      "args": ["-y", "smartleadai-mcp"],
      "env": {
        "SMARTLEAD_API_KEY": "sl_your_key",
        "SMARTLEAD_MCP_MODE": "readonly"
      }
    }
  }
}

Hermes

Add this under mcp_servers in ~/.hermes/config.yaml (use hermes config path to locate the active profile's file):

mcp_servers:
  smartlead:
    command: "npx"
    args: ["-y", "smartleadai-mcp"]
    env:
      SMARTLEAD_API_KEY: "sl_your_key"
      SMARTLEAD_MCP_MODE: "readonly"
      SMARTLEAD_MCP_ALLOW_CREDIT_SPEND: "false"

Restart Hermes, then verify with hermes mcp test smartlead. Hermes filters the subprocess environment, so the API key must be present in this server's env mapping rather than merely exported in an unrelated shell.

Any other stdio MCP client

Launch the process with the API key in its environment and speak MCP over stdin/stdout:

{
  "command": "npx",
  "args": ["-y", "smartleadai-mcp"],
  "transport": "stdio",
  "env": { "SMARTLEAD_API_KEY": "sl_your_key" }
}

Programmatic use (for embedding in your own host):

import { createServer, loadConfig } from 'smartleadai-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const { server } = createServer(loadConfig());
await server.connect(new StdioServerTransport());

Environment variables

Variable	Required	Default	Notes
`SMARTLEAD_API_KEY`	yes	—	Read from the environment only. It can never be passed as a tool argument.
`SMARTLEAD_CORE_BASE_URL`	no	`https://server.smartlead.ai/api/v1`	Core Smartlead host.
`SMARTLEAD_PROSPECT_BASE_URL`	no	`https://prospect-api.smartlead.ai/api/v1/search-email-leads`	SmartProspect host.
`SMARTLEAD_DELIVERY_BASE_URL`	no	`https://smartdelivery.smartlead.ai/api/v1`	Smart Delivery host.
`SMARTLEAD_SENDERS_BASE_URL`	no	`https://smart-senders.smartlead.ai/api/v1`	Smart Senders host.
`SMARTLEAD_MCP_MODE`	no	`readonly`	`readonly` \| `standard` \| `unrestricted`.
`SMARTLEAD_MCP_ALLOW_CREDIT_SPEND`	no	`false`	Literal `true`/`false`.
`SMARTLEAD_MCP_ALLOW_SEND`	no	`false`	Literal `true`/`false`.
`SMARTLEAD_MCP_ALLOW_DESTRUCTIVE`	no	`false`	Literal `true`/`false`.
`SMARTLEAD_MCP_TIMEOUT_MS`	no	`30000`	Per-request timeout, 1000–600000.
`SMARTLEAD_MCP_MAX_RETRIES`	no	`2`	Extra attempts, 0–5. Applies to safe GETs only.
`SMARTLEAD_LIVE_TESTS`	no	`false`	Development only; enables the opt-in read-only live test suite.

Boolean flags accept only the literal strings true and false (case insensitive). 1, yes and on are rejected so a typo can never silently enable spending.

See .env.example.

Safety modes

	`readonly` (default)	`standard`	`unrestricted`
Read-only operations	allowed	allowed	allowed
Remote mutations (saved searches, campaign drafts, lead import, block-list add)	blocked	allowed	allowed
Credit spending	blocked	needs env flag and `confirm_credit_spend: true`	needs env flag and `confirm_credit_spend: true`
Sending / campaign activation	blocked	blocked	needs `SMARTLEAD_MCP_ALLOW_SEND=true` and `confirm_send: true`
Destructive operations	blocked	blocked	needs `SMARTLEAD_MCP_ALLOW_DESTRUCTIVE=true` and `confirm_destructive: true`
Lead import	blocked	needs `confirm_import: true`	needs `confirm_import: true`

Rules that hold in every mode:

A confirmation field must be boolean true. "true", 1 and "yes" are rejected. There is no confirmation field that defaults to true.
A blocked call is refused before any HTTP request is made, so a blocked credit-spending call costs nothing.
Refusals come back as a normal structured envelope with error.kind: "policy", a machine-readable error.code, and an error.requirements array telling the operator exactly what to change.

Tool reference

183 tools across four hosts. The full table would be unreadable here, so list them from the CLI instead — it prints each tool's safety classification:

smartleadai-mcp tools              # all 183
smartleadai-mcp tools campaign     # filter by substring

Host	Base URL	Tools	Prefix
SmartProspect	`prospect-api.smartlead.ai/api/v1/search-email-leads`	26	`smartprospect_`
Core	`server.smartlead.ai/api/v1`	128	`smartlead_`
Smart Delivery	`smartdelivery.smartlead.ai/api/v1`	24	`smartdelivery_`
Smart Senders	`smart-senders.smartlead.ai/api/v1`	5	`smartsenders_`

By safety classification:

Classification	Tools	Gate
Read-only	113	none — available in every mode
Remote mutation	70	`standard` mode or above
Sends email	10	`unrestricted` + `ALLOW_SEND` + `confirm_send`
Destructive	12	`unrestricted` + `ALLOW_DESTRUCTIVE` + `confirm_destructive`
Consumes credits	2	`ALLOW_CREDIT_SPEND` + `confirm_credit_spend` + preflight

Classification is reviewed per endpoint, not inferred from the HTTP verb. Smartlead serves 14 searches over POST — those are read-only. Several DELETE and stop/suspend/block routes are suppression-increasing and are deliberately not destructive, so the safe action is never harder to take than the dangerous one.

Every tool returns the same envelope:

{
  "ok": true,
  "operation": "smartprospect_search_contacts",
  "credit_spending": false,
  "remote_mutation": false,
  "data": { "list": [] },
  "pagination": { "scroll_id": "…", "filter_id": 327105, "total_count": 16064669 },
  "warnings": []
}

The SmartProspect workflow

SmartProspect separates searching (free) from revealing (paid). The tools mirror that split.

1. Inspect credits. Always first, always free.

// smartprospect_get_search_analytics
{}
// → data.availableCredits { available, total, used }, maxSingleFetchLimit, maxDailyFetchLimit

2. Build valid filter values. Free lookups: smartprospect_list_countries, _list_states, _list_cities, _list_industries, _list_sub_industries, _list_departments, _list_seniority_levels, _list_head_counts, _list_revenue_ranges, _list_companies, _list_domains, _list_job_titles, _list_keywords.

3. Search previews. Free. Returns a page of candidates plus the filter_id you will need later, the total_count of matches, and a scroll_id for the next page. Preview records are de-identified by default; set include_full_records: true only when names and personal fields are needed.

// smartprospect_search_contacts
{
  "limit": 25,
  "title": ["Head of Growth"],
  "country": ["United States"],
  "companyHeadCount": ["25 - 100"],
  "titleExactMatch": false
}

4. Review candidates. Page with scroll_id, narrow the filters, and — if you want to avoid sending personal data to the model at all — pass include_full_records: false to receive a de-identified summary.

Optionally persist the filter:

// smartprospect_save_search   (standard mode or above)
{ "search_string": "US Heads of Growth, 25-100", "title": ["Head of Growth"], "country": ["United States"] }

5. Intentionally reveal selected contacts. This is the step that spends credits, and it is doubly gated.

// smartprospect_fetch_contacts   (needs SMARTLEAD_MCP_ALLOW_CREDIT_SPEND=true)
{ "filter_id": 327105, "limit": 50, "visual_limit": 50, "confirm_credit_spend": true }

or, for a handful of named people you already know:

// smartprospect_find_emails      (max 10 per call)
{
  "contacts": [{ "firstName": "Ada", "lastName": "Lovelace", "companyDomain": "example.com" }],
  "confirm_credit_spend": true
}

6. Retrieve contacts you already paid for. Free — never re-fetch.

// smartprospect_get_contacts
{ "filter_id": 327105, "limit": 100, "offset": 0, "verification_status": "valid" }

Use smartprospect_list_fetched_searches to find filters whose contacts have already been revealed, and smartprospect_review_contacts to re-sync a filter's metrics.

Controlling credit spend

Credit-consuming tools are gated at three independent layers:

Process configuration. SMARTLEAD_MCP_ALLOW_CREDIT_SPEND=true must be set in the server's environment. Without it, the tool refuses and no HTTP request is made.
Per-call confirmation. The call must include confirm_credit_spend: true as a real boolean.
Credit preflight (smartprospect_fetch_contacts only). Before the paid request, the tool calls the free search-analytics endpoint and compares the requested quantity against availableCredits.available and maxSingleFetchLimit. If the request exceeds either, it is rejected with an explanation — never silently reduced. The preflight result is returned in data.credit_preflight.

// Refused: env flag not set. No request was sent to Smartlead.
{
  "ok": false,
  "operation": "smartprospect_fetch_contacts",
  "credit_spending": false,
  "remote_mutation": false,
  "data": null,
  "pagination": null,
  "warnings": [],
  "error": {
    "kind": "policy",
    "code": "credit_spend_disabled",
    "message": "This operation can consume SmartProspect credits and credit spending is disabled.",
    "requirements": ["Set SMARTLEAD_MCP_ALLOW_CREDIT_SPEND=true and restart the MCP server."]
  }
}

// Refused: request larger than the balance. Only the free preflight ran.
{
  "ok": false,
  "error": {
    "kind": "refusal",
    "code": "insufficient_credits",
    "message": "Requested 900 contact(s) but only 100 SmartProspect credit(s) are available. The request was not sent and no credits were spent.",
    "requirements": ["Reduce the request to 100 or fewer.", "Or top up SmartProspect credits in the Smartlead dashboard."]
  }
}

Neither credit-consuming request is ever retried automatically. Retries are enabled only for safe idempotent GETs.

The preflight cannot be skipped. If analytics is unavailable or does not return recognisable credit and account-limit fields, the paid request fails closed.

Error handling

Failures never throw across the MCP boundary. They come back as an envelope with ok: false and a typed error.kind:

`error.kind`	Meaning
`policy`	Blocked locally by the safety policy. No HTTP request was made.
`refusal`	Blocked locally by a tool-level check (e.g. insufficient credits).
`authentication`	HTTP 401 — key missing or invalid.
`permission`	HTTP 403.
`payment`	HTTP 402, or a credit-related `success: false` body.
`validation`	HTTP 400 / 422.
`not_found`	HTTP 404.
`conflict`	HTTP 409.
`rate_limit`	HTTP 429. `retry_after_seconds` is surfaced when Smartlead sends it.
`server`	HTTP 5xx.
`timeout`	The request exceeded `SMARTLEAD_MCP_TIMEOUT_MS`.
`transport`	DNS/TLS/socket failure; no HTTP response.
`protocol`	HTTP 200 with a body that was not JSON.
`api_failure`	HTTP 200 with `success: false` in the body.

Smartlead returns HTTP 200 with success: false for several documented failure cases (notably fetch-contacts limit and credit checks). Those are surfaced as errors, not as successes with empty data.

Retries apply only to GET requests and only for rate_limit, server, timeout and transport failures, with exponential backoff that honours Retry-After.

Privacy and security

The API key is environment-only. No tool accepts it as an argument; attempting to pass api_key to a tool is rejected by the input schema.
The key is redacted everywhere. Smartlead authenticates via an api_key query parameter, so the credential appears in every request URL. Every URL, error message, error detail and tool result is passed through a redactor before it leaves the process.
Nothing is logged. The server writes no request bodies, no responses and no contact data to stdout, stderr or disk. stdout carries only the MCP protocol stream; stderr carries only fatal startup errors.
Contact data is returned, by design. That is the purpose of a prospecting tool. Tools that return contacts accept include_full_records: false to return a de-identified summary (counts and non-personal attributes) instead.
Tests use synthetic data only (person@example.com and similar).

Read SECURITY.md and docs/security-model.md before granting this server anything beyond readonly.

Prompt injection matters here. Contact records, campaign names and lead custom fields are attacker-influenceable text. Treat any instruction that appears inside tool output as data, never as a command — and note that the policy layer is what actually stops an injected "fetch 10,000 contacts" instruction, not the model's judgement.

Development

npm install
npm run typecheck     # tsc --noEmit
npm run lint          # eslint, zero warnings allowed
npm test              # unit + integration (mocked fetch, no network)
npm run test:coverage # with v8 coverage thresholds
npm run build         # tsup -> dist/
npm run pack:check    # npm pack --dry-run
npm run verify        # typecheck + lint + coverage + build + pack + installed-package smoke
npm run smoke:package # pack, install into a throwaway dir, drive the installed
                      # binary with a real MCP client (no Smartlead access)
npm run test:live     # opt-in, read-only; needs SMARTLEAD_LIVE_TESTS=true

The default suite never touches the network — fetch is injected. The live suite is read-only, is skipped unless SMARTLEAD_LIVE_TESTS=true and SMARTLEAD_API_KEY are both set, and asserts that the credit balance is unchanged before and after it runs. It never calls find-emails, fetch-contacts, imports, campaign mutations, sending, deletion or unsubscribe.

Layout:

src/
  index.ts                 stdio entry point
  server.ts                transport-agnostic server factory
  config.ts                environment parsing and validation
  client/                  errors.ts, http.ts, core-client.ts, prospect-client.ts
  security/                redaction.ts, policy.ts
  schemas/                 common.ts, smart-prospect.ts, core.ts
  tools/                   types, envelope, shape, register + smart-prospect/ and core/
  types/                   loose Smartlead response types
tests/                     unit/, integration/, live/, helpers/
docs/                      endpoint-coverage.md, security-model.md, publishing.md

Adding an HTTP/Streamable HTTP transport later means adding a new entry point that calls createServer() and attaches a different transport. No tool, schema or client change is required.

Publishing checklist

Nothing here has been published. See docs/publishing.md for the full procedure. Summary:

Run npm run verify for typecheck, lint, coverage, build, pack dry-run and a clean installed-package MCP smoke test. prepublishOnly repeats every check except the nested pack/install smoke, which npm cannot run recursively while already preparing a publish.
Confirm the packed file list contains only dist/, the public Markdown documentation, .env.example, and package.json.
Confirm you are authenticated on npm. The name is unscoped, so no scope membership is needed — but nothing reserves it either until it is published.
Tag, publish with --access public (optionally --provenance), then run a post-publication smoke test from a clean directory.

Useful links

Using Smartlead.ai MCP Safely — Voriq's guide to configuring and using this MCP server safely.

Official Smartlead documentation

Introduction — https://api.smartlead.ai/introduction
Authentication — https://api.smartlead.ai/authentication
Machine-readable index — https://api.smartlead.ai/llms.txt and https://api.smartlead.ai/llms-full.txt
Rate limits — https://api.smartlead.ai/guides/rate-limits
Error handling — https://api.smartlead.ai/guides/error-handling
SmartProspect reference — https://api.smartlead.ai/api-reference/smart-prospect/search-contacts (and siblings)

Per-endpoint source pages, with the date each was checked, are listed in docs/endpoint-coverage.md.

Known limitations

Unsafe or undocumented operations are excluded. These include mailbox credential ingestion, client API-key management, live OTP retrieval, domain purchases, and sending or Smart Delivery operations whose request schema is absent from the official page. A duplicate lead-update page is also collapsed into the canonical tool. See docs/endpoint-coverage.md for the full list.
Most tools are catalog-generated. The 39 hand-written tools encode every documented range, enum and cross-field rule (such as the id/filter_id XOR). Another 144 are generated from corrected documentation metadata. The correction layer removes flattened nested fields, fixes documented integer types, applies reviewed safety overrides, and enforces known cross-field rules.
This server can send email. With unrestricted mode plus SMARTLEAD_MCP_ALLOW_SEND=true, 10 tools can put mail in a real recipient's inbox, including smartlead_utilities_send_single_email. The gate stops accidents, not a determined agent that has been given the flag.
fetch-contacts elevated limit is unverifiable locally. Smartlead documents 1–10000 "or 30000 for some users" without exposing which applies. The schema accepts up to 30000 and warns above 10000; the account's real maxSingleFetchLimit from the preflight is what is actually enforced.
Daily fetch limits are enforced from analytics. If the requested quantity plus leadsFoundToday exceeds maxDailyFetchLimit, the paid request is refused locally.
Undocumented maximums are guarded, not derived. A few lookup endpoints document a default but no maximum; this package applies a client-side bound (noted in docs/endpoint-coverage.md) rather than inventing a documented one.
Rate-limit tiers are per account. Smartlead documents 60–120 requests per minute depending on plan. This server does not throttle; it retries safe GETs with backoff and surfaces rate_limit errors otherwise.
Response shapes are passed through. Smartlead's response envelopes vary between endpoint families; tools unwrap the common { success, message, data } wrapper but do not otherwise normalise upstream field names.
Limited live verification. Independent review exercised search analytics, countries, and a one-result filtered contact search through the assembled MCP server. The account credit balance was unchanged. Mutations and paid endpoints remain mocks-only by design.

Licence

MIT — see LICENSE and THIRD_PARTY_NOTICES.md.

"Smartlead" and "SmartProspect" are trademarks of their respective owner. This project is not affiliated with, endorsed by, or sponsored by Smartlead.ai, and uses those names only to identify the API it integrates with.

Available Tools

39 tools

smartlead_add_domain_to_block_listSmartlead: add domains to the block listA

Add domains or email addresses to the global block list so no campaign emails them. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: POST https://server.smartlead.ai/api/v1/leads/add-domain-block-list. Creates remote state. Blocked in readonly mode. Does not send email. This is a suppression action: it reduces, never increases, outbound sending.

Inputs: domain_block_list (required), client_id. Returns: ok, data, error, warnings, +4 more

smartlead_add_leads_to_campaignSmartlead: add leads to a campaignA

Destructive

Import leads into an explicitly named campaign. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: yes. Endpoint: POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads. Creates remote state. Blocked in readonly mode. Requires an explicit campaign_id and confirm_import: true. Maximum 400 leads per call. Duplicate emails are removed locally (case-insensitive, trimmed) before the request and the number removed is reported. Never activates the campaign — use smartlead_update_campaign_status separately. Bypassing the global block list, unsubscribe list, duplicate protection or community bounce list is classified as destructive and requires unrestricted mode plus destructive confirmation. Never auto-retried: a retry could import leads twice.

Inputs: lead_list (required), campaign_id (required), settings, confirm_import, +1 more. Returns: ok, data, error, warnings, +4 more

smartlead_create_campaignSmartlead: create campaignA

Create a new Smartlead campaign. Smartlead creates it in DRAFTED status. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: POST https://server.smartlead.ai/api/v1/campaigns/create. Creates remote state. Blocked in readonly mode. The new campaign is a draft: it does not send anything until it is explicitly started. Never auto-retried — a retry could create a duplicate campaign.

Inputs: name, client_id. Returns: ok, data, error, warnings, +4 more

smartlead_get_campaignSmartlead: get campaignA

Read-only

Retrieve full configuration for one campaign by ID. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}. Free and read-only.

Inputs: campaign_id (required), include_tags. Returns: ok, data, error, warnings, +4 more

smartlead_get_campaign_analyticsSmartlead: get campaign analyticsA

Read-only

Retrieve performance analytics for one campaign (sent, opened, replied, bounced). Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/analytics. Free and read-only.

Inputs: campaign_id (required). Returns: ok, data, error, warnings, +4 more

smartlead_get_campaign_leadsSmartlead: get campaign leadsA

Read-only

List leads in a campaign with pagination and status/engagement filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads. Free and read-only. Returns personal data (lead email addresses and names).

Inputs: campaign_id (required), limit, offset, status, +5 more. Returns: ok, data, error, warnings, +4 more

smartlead_get_domain_block_listSmartlead: get domain block listA

Read-only

List blocked domains and email addresses with their source and client association. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/leads/get-domain-block-list. Free and read-only.

Inputs: limit, offset, filter_client_id, filter_email_or_domain, +1 more. Returns: ok, data, error, warnings, +4 more

smartlead_get_lead_by_emailSmartlead: get lead by emailA

Read-only

Look up a single lead by email address and return its associated campaign data. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/leads/. Free and read-only. Returns personal data for the matched lead.

Inputs: email (required). Returns: ok, data, error, warnings, +4 more

smartlead_list_campaignsSmartlead: list campaignsA

Read-only

List all Smartlead campaigns with status, schedule and sending configuration. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/campaigns/. Free and read-only.

Inputs: client_id, include_tags. Returns: ok, data, error, warnings, +4 more

smartlead_list_email_accountsSmartlead: list email accountsA

Read-only

List connected sending accounts with warmup, SMTP and provider filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/email-accounts/. Free and read-only. Returns mailbox addresses, which are personal data.

Inputs: esp, limit, offset, isInUse, +6 more. Returns: ok, data, error, warnings, +4 more

smartlead_list_lead_listsSmartlead: list lead listsA

Read-only

List saved lead lists with optional name and tag filtering. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://server.smartlead.ai/api/v1/lead-list/. Free and read-only.

Inputs: limit, offset, tagIds, listName. Returns: ok, data, error, warnings, +4 more

smartlead_remove_domain_from_block_listSmartlead: remove an entry from the block listA

Destructive

Delete one entry from the global block list, re-enabling outreach to that domain or address. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: yes. Endpoint: DELETE https://server.smartlead.ai/api/v1/leads/delete-domain-block-list. Classified as DESTRUCTIVE: it deletes a suppression record and re-enables sending to a previously blocked recipient. Requires unrestricted mode, SMARTLEAD_MCP_ALLOW_DESTRUCTIVE=true and confirm_destructive: true. Call smartlead_get_domain_block_list first to confirm which entry the ID refers to.

Inputs: id (required), confirm_destructive. Returns: ok, data, error, warnings, +4 more

smartlead_update_campaign_statusSmartlead: update campaign statusA

Destructive

Start, pause or stop a campaign. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: yes; destructive: yes. Endpoint: POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/status. PAUSED is an ordinary mutation and works in standard mode. START activates the campaign and will cause email to be sent: it requires unrestricted mode, SMARTLEAD_MCP_ALLOW_SEND=true and confirm_send: true. STOPPED permanently stops the campaign and cannot be undone: it requires unrestricted mode, SMARTLEAD_MCP_ALLOW_DESTRUCTIVE=true and confirm_destructive: true. Smartlead documents the activation value as "START", not "ACTIVE".

Inputs: status (required), campaign_id (required), confirm_send, confirm_destructive. Returns: ok, data, error, warnings, +4 more

smartprospect_fetch_contactsSmartProspect: fetch contacts for a filter (consumes credits)A

Reveal contact email addresses for a saved filter, either by explicit adapt IDs or by a bounded limit. CONSUMES SMARTPROSPECT CREDITS. Safety — read-only: no; may consume SmartProspect credits: yes; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: POST https://prospect-api.smartlead.ai/api/v1/search-email-leads/fetch-contacts. Provide exactly one of id (explicit adapt IDs) or limit. Documented limit range is 1-10000 (up to 30000 on some accounts). Requires SMARTLEAD_MCP_ALLOW_CREDIT_SPEND=true and confirm_credit_spend: true. Runs a free, read-only credit preflight first and rejects — never silently reduces — a request that exceeds available credits or the account single-fetch limit. Never retried automatically.

Inputs: filter_id (required), id, limit, visual_limit, +3 more. Returns: ok, data, error, warnings, +4 more

smartprospect_find_emailsSmartProspect: find emails (consumes credits)A

Look up email addresses for up to 10 named contacts at their company domains. CONSUMES SMARTPROSPECT CREDITS. Safety — read-only: no; may consume SmartProspect credits: yes; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: POST https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-contacts/find-emails. Maximum 10 contacts per call; each contact requires firstName, lastName and companyDomain. Requires SMARTLEAD_MCP_ALLOW_CREDIT_SPEND=true and confirm_credit_spend: true. Without both, the call is refused locally without contacting Smartlead. Never retried automatically — a retry could be charged twice. Check smartprospect_get_search_analytics first to see the credit balance.

Inputs: contacts (required), confirm_credit_spend, include_full_records. Returns: ok, data, error, warnings, +4 more

smartprospect_get_contactsSmartProspect: get already-fetched contactsA

Read-only

Retrieve contacts that were already saved or fetched, by adapt IDs or by filter_id, with optional verification and catch-all filtering. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: POST https://prospect-api.smartlead.ai/api/v1/search-email-leads/get-contacts. Read-only. Returns contacts whose emails were already paid for; it does not spend credits. Provide exactly one of id (max 200 adapt IDs) or filter_id — never both. limit, offset, search, verification_status and catch_all_status apply when using filter_id.

Inputs: id, limit, offset, search, +4 more. Returns: ok, data, error, warnings, +4 more

smartprospect_get_reply_analyticsSmartProspect: reply analyticsA

Read-only

Return SmartProspect reply counts for the current and previous month, with the trend. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/reply-analytics. Free and read-only.

Inputs: no named parameters. Returns: ok, data, error, warnings, +4 more

smartprospect_get_search_analyticsSmartProspect: search analytics and credit balanceA

Read-only

Return SmartProspect credit balance (available/total/used), daily and single-fetch limits, and leads-found / emails-fetched metrics. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-analytics. Read this before any credit-consuming call. Free and read-only. Pass filter_id to also get per-filter leads-found and emails-fetched figures.

Inputs: filter_id. Returns: ok, data, error, warnings, +4 more

smartprospect_list_citiesSmartProspect: list citiesA

Read-only

List city values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/cities. Reference data only. Does not reveal contacts and does not consume credits. Smartlead documents that filtering by country also requires state.

Inputs: limit, state, offset, search, +1 more. Returns: ok, data, error, warnings, +4 more

smartprospect_list_companiesSmartProspect: list companiesA

Read-only

List company names available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/company. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_countriesSmartProspect: list countriesA

Read-only

List country values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/countries. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_departmentsSmartProspect: list departmentsA

Read-only

List department values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/departments. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_domainsSmartProspect: list company domainsA

Read-only

List company domains available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/domain. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_fetched_searchesSmartProspect: list fetched searchesA

Read-only

List searches whose contacts have already been fetched, including per-filter fetch metrics (total contacts, emails, bounces). Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/fetched-searches. Free and read-only. Contacts listed here were already paid for; retrieve them with smartprospect_get_contacts rather than fetching again.

Inputs: limit, offset. Returns: ok, data, error, warnings, +4 more

smartprospect_list_head_countsSmartProspect: list company head count rangesA

Read-only

List company head count (size) ranges available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/head-counts. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_industriesSmartProspect: list industriesA

Read-only

List industry values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/industries. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search, withSubIndustry. Returns: ok, data, error, warnings, +4 more

smartprospect_list_job_titlesSmartProspect: list job titlesA

Read-only

List job title values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/job-title. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_keywordsSmartProspect: list company keywordsA

Read-only

List company keyword values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/keywords. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_recent_searchesSmartProspect: list recent searchesA

Read-only

List recently executed SmartProspect searches with their filter details. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/recent-searches. Free and read-only.

Inputs: limit, offset. Returns: ok, data, error, warnings, +4 more

smartprospect_list_revenue_rangesSmartProspect: list revenue rangesA

Read-only

List company revenue range values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/revenue. Reference data only. Does not reveal contacts and does not consume credits. This endpoint takes no pagination parameters.

Inputs: no named parameters. Returns: ok, data, error, warnings, +4 more

smartprospect_list_saved_searchesSmartProspect: list saved searchesA

Read-only

List saved SmartProspect search filters with their stored filter details. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/saved-searches. Free and read-only. Use the returned id as a filter_id elsewhere.

Inputs: limit, offset. Returns: ok, data, error, warnings, +4 more

smartprospect_list_seniority_levelsSmartProspect: list seniority levelsA

Read-only

List seniority level values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/levels. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search. Returns: ok, data, error, warnings, +4 more

smartprospect_list_statesSmartProspect: list statesA

Read-only

List state/region values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/states. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search, country. Returns: ok, data, error, warnings, +4 more

smartprospect_list_sub_industriesSmartProspect: list sub-industriesA

Read-only

List sub-industry values available as SmartProspect search filters. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: GET https://prospect-api.smartlead.ai/api/v1/search-email-leads/sub-industries. Reference data only. Does not reveal contacts and does not consume credits.

Inputs: limit, offset, search, industry_id. Returns: ok, data, error, warnings, +4 more

smartprospect_review_contactsSmartProspect: review (re-sync) contacts for a filterA

Re-sync contact metrics and statuses for a SmartProspect filter, returning updated counts for emails, bounces and verification. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: PATCH https://prospect-api.smartlead.ai/api/v1/search-email-leads/review-contacts/{filter_id}. Modifies remote state (records are updated) but does not consume credits. Blocked in readonly mode.

Inputs: filter_id (required). Returns: ok, data, error, warnings, +4 more

smartprospect_save_searchSmartProspect: save a search filterA

Save a named SmartProspect search filter for later reuse. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: POST https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/save-search. Creates remote state. Does not run the search and does not consume credits. Blocked in readonly mode.

Inputs: search_string (required), city, name, level, +24 more. Returns: ok, data, error, warnings, +4 more

smartprospect_search_contactsSmartProspect: search contactsA

Read-only

Search the SmartProspect contact database with filters and return a preview page plus filter_id, total_count and scroll_id. Safety — read-only: yes; may consume SmartProspect credits: no; creates or modifies remote state: no; can send email: no; destructive: no. Endpoint: POST https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-contacts. Read-only. Running a search does not fetch or reveal credit-gated contacts and does not spend credits by itself. limit is required and must be 1-500; every array filter accepts at most 2000 items. Pass the returned scroll_id back in to page through results; keep the filter_id to fetch or retrieve contacts later.

Inputs: limit (required), city, name, level, +25 more. Returns: ok, data, error, warnings, +4 more

smartprospect_update_fetched_searchSmartProspect: rename a fetched searchA

Rename an existing fetched SmartProspect search (fetched lead set). Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: PUT https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/fetched-searches/{id}. Modifies remote state. Blocked in readonly mode. Does not consume credits.

Inputs: id (required), search_string (required). Returns: ok, data, error, warnings, +4 more

smartprospect_update_saved_searchSmartProspect: rename a saved searchA

Rename an existing saved SmartProspect search filter. Safety — read-only: no; may consume SmartProspect credits: no; creates or modifies remote state: yes; can send email: no; destructive: no. Endpoint: PUT https://prospect-api.smartlead.ai/api/v1/search-email-leads/search-filters/save-search/{id}. Modifies remote state. Blocked in readonly mode. Does not consume credits.

Inputs: id (required), search_string (required). Returns: ok, data, error, warnings, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-14 04:45 across 39 tools

Disambiguation4/5

The tools are clearly separated into SmartProspect and Smartlead domains, and most actions target distinct resources. However, smartprospect_get_contacts, smartprospect_fetch_contacts, and smartprospect_find_emails all relate to obtaining contacts/emails with subtle differences that could cause misselection despite detailed descriptions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with domain prefixes (smartprospect_/smartlead_). Reference data tools use list_*, actions use get_, create_, update_, etc., producing a predictable and readable naming convention.

Tool Count2/5

With 39 tools, the server is quite heavy, exceeding the typical well-scoped range. Many are reference data listers (countries, states, cities, etc.) that could be consolidated, making the surface feel bloated even though the two domains are clear.

Completeness3/5

Core workflows are covered (search, fetch, campaign management, lead import, block list management), but notable lifecycle gaps exist: no delete for saved searches or campaigns, no remove leads from campaign, and no campaign content update. Agents may hit dead ends when needing these operations.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

gtm-api: LinkedIn MCP ServerA
com.gtm-api
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
Social Media Communication
3167
https://mcp.gtm-api.com/mcp
LeadDelta MCP Server
io.github.LeadDelta
MCP server for LeadDelta — manage LinkedIn connections and CRM data via AI assistants.
Customer Data Platforms Social Media Marketing
2
https://mcp.leaddelta.com/mcp
Fintalio LinkedIn MCP
com.fintalio
LinkedIn outreach MCP server — 19 tools for AI agents to prospect, sequence, and manage contacts.
Communication CRM Social Media
2
https://fintalio.com/mcp
Relm CRMA
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412
https://api.relmcrm.com/mcp

Related MCP Servers

Smartlead Simplified MCP
Marketing App Automation
jonathan-politzki
A
license
B
quality
D
maintenance
A Multi-Channel Proxy server that provides a structured interface for interacting with Smartlead's API, organizing functionality into logical tools for campaign management, lead management, and other marketing automation features.
Updated a year ago (2025-07-23 21:09 UTC)
20
83 npm
18
MIT
SmartLead MCP Server
API Testing Marketing App Automation
LeadMagic
A
license
Not graded
quality
F
maintenance
A Model Context Protocol server that provides AI coding assistants (Claude, Cursor, etc.) with access to SmartLead's cold email automation platform through 116+ API endpoints for campaign management, lead tracking, and email delivery.
Updated 2 months ago (2026-09-07 01:53 UTC)
1,133 npm
20
MIT
smartlead-mcp-server-sse
Email CRM Marketing
jacob-dietle
A
license
Not graded
quality
C
maintenance
An MCP server that enables AI agents to manage Smartlead campaigns, including creating campaigns, updating schedules, managing email sequences, and adding leads, all over SSE.
Updated a year ago (2025-05-21 06:11 UTC)
272 npm
5
MIT
Prosp MCP Server
CRM Communication
AvolveAi
A
license
A
quality
D
maintenance
MCP server for Prosp.ai LinkedIn outreach automation. Manage leads, campaigns, messaging, and analytics programmatically.
Updated 8 months ago (2026-03-10 19:29 UTC)
17
1
MIT

smartleadai-mcp

Table of contents

Why this exists

Requirements

Installation

Command line

Client configuration

Claude Desktop

Hermes

Any other stdio MCP client

Environment variables

Safety modes

Tool reference

The SmartProspect workflow

Controlling credit spend

Error handling

Privacy and security

Development

Publishing checklist

Useful links

Official Smartlead documentation

Known limitations

Licence

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Smartlead Simplified MCP

SmartLead MCP Server

smartlead-mcp-server-sse

Prosp MCP Server