Skip to main content
Glama
ZeroBounce MCP Open Source

ZeroBounce MCP Open Source

Official

ZeroBounce MCP Server

npm version License: MIT MCP MCP Badge

Connect your AI assistant to your ZeroBounce account. The ZeroBounce Model Context Protocol server lets Claude, ChatGPT, Cursor, VS Code and any other MCP client validate and score email addresses, find emails and domains, clean lists in bulk, run inbox placement tests and manage Warmup.

The easiest way to use it is the hosted server at https://mcp.zerobounce.net/mcp. You sign in with your ZeroBounce account, so there is nothing to install and no API key to copy. This repository is the open-source version of the same tools: the @zerobounce/mcp package, which you run yourself with an API key (Run it yourself).

Features

  • Email validation: one address, up to 200 in one call, or whole CSV files in bulk

  • AI scoring: how likely an address is to engage, for one address or a bulk file

  • Email finder and domain search: a work email from a name and domain, or a domain's email format

  • Activity data: whether an address has been active recently

  • List Evaluator: a free quality estimate of a list before you validate it

  • Allow and block filters on your account

  • Amazon S3 and SFTP/FTP bulk jobs: validate, score and export files already in your storage

  • Inbox placement testing: whether a campaign lands in the inbox or in spam at each provider

  • Warmup: sending accounts, engagement rules, seeds, statistics and SPF/DKIM/DMARC checks

  • Credits and API usage for your account

Tools that spend credits or change your account say so in their description, and deletes are marked destructive, so your assistant asks before calling them. See Tools.

Related MCP server: @deliveriq/mcp

Connect to the hosted server

Add https://mcp.zerobounce.net/mcp to your client as a remote (HTTP) MCP server. No API key or header goes in the configuration: the first time the client connects, it opens ZeroBounce in your browser to sign in.

Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector, with the URL https://mcp.zerobounce.net/mcp.

Claude Code:

claude mcp add --transport http zerobounce https://mcp.zerobounce.net/mcp

ChatGPT: add a custom connector (app) with the URL https://mcp.zerobounce.net/mcp and OAuth authentication, where your plan allows custom connectors.

Cursor — install the plugin from this repo (Customize → Plugins → Import from GitHub → zerobounce/zerobounce-mcp): hosted MCP + the zerobounce skill. See docs/CURSOR_MARKETPLACE.md.

Or add the URL manually in ~/.cursor/mcp.json or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "zerobounce": {
      "url": "https://mcp.zerobounce.net/mcp"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "zerobounce": {
      "type": "http",
      "url": "https://mcp.zerobounce.net/mcp"
    }
  }
}

Gemini CLI — install the extension from this repo; it connects to the hosted server and signs you in with OAuth on first use:

gemini extensions install https://github.com/zerobounce/zerobounce-mcp

Then ask your assistant, for example:

How many ZeroBounce credits do I have left?
Validate jane.doe@example.com

Signing in and choosing permissions

The hosted server uses OAuth 2.1 with dynamic client registration, so clients set themselves up automatically. When you connect, ZeroBounce shows a consent page where you:

  1. Sign in to your ZeroBounce account.

  2. Choose what the assistant may do. Reading your account (credit balance, usage, bulk file status and results, filters, inbox placement tests) is always granted. Each of these is optional:

    • Spend credits: validate and score emails, look up activity data, find emails and domains.

    • Change account data (marked high risk): upload and delete bulk files, start S3/SFTP jobs, manage filters and inbox placement tests, and run batch validation.

    • Warmup: the Warmup tools, using your team's Warmup API key. Offered to Owners and Admins once the team has generated a Warmup key.

  3. Pick the tools within those permissions, and the API region: Default, US or EU. Single-address calls use that region's API. Bulk files, the Inbox Placement Tester and Warmup have no regional hosts and always use the global ones.

Your assistant only sees, and can only call, the tools you approved. To change them later, or to get tools added in a server update, disconnect and connect again. Account Owners, Admins and Devs can connect; team members without API access cannot.

Each connection is limited to 300 requests and 60 credit-spending tool calls per minute.

For AI agents, https://mcp.zerobounce.net/llms.txt describes how to connect and lists every tool.

Hosted or self-hosted?

Hosted (mcp.zerobounce.net)

Self-hosted (@zerobounce/mcp)

Setup

Add a URL, sign in

Install Node.js 22+ and the npm package

Credentials

OAuth sign-in; no key in your config

Your API key (and Warmup key) in the config or environment

Permissions

Chosen per connection on the consent page

Everything the API key can do

Clients

Any client that supports remote MCP servers (Claude, ChatGPT, Cursor, VS Code, ...)

stdio clients, or your own HTTP deployment

Tools

Same tool names, titles and annotations

Same tool names, titles and annotations; argument names are camelCase (fileId, ipAddress) and bulk uploads take CSV text

Use the hosted server unless you need to run everything on your own machine or network, pin a specific version, or use a client without remote MCP support.

Run it yourself

The npm package runs the same tools locally over stdio, or as your own HTTP server, with your ZeroBounce API key.

Quick start

Requires Node.js 22 or later (check with node --version).

  1. Install the MCP server globally

    npm install -g @zerobounce/mcp

    This installs the zerobounce-mcp command.

  2. Get your ZeroBounce API key from the ZeroBounce dashboard (Getting your API key).

  3. Add it to your MCP client (Cursor, VS Code, Claude Desktop, etc.):

    {
      "mcpServers": {
        "zerobounce": {
          "command": "zerobounce-mcp",
          "args": ["--api-key=YOUR_API_KEY"]
        }
      }
    }
  4. Start using it in your AI assistant:

    Validate the email address "test@example.com"

Getting your API key

Your ZeroBounce API key is available in the ZeroBounce dashboard:

  • Sign in to your ZeroBounce account

  • Navigate to the API / Developer or Integrations section

  • Create or copy an API key for this integration

  • Use different keys for development, staging, and production when possible

Note: Treat your API key like a password. Do not share it or commit it to version control. The hosted server needs no key: you sign in instead.

Warmup API key

Warmup is a separate ZeroBounce product with its own API key and its own host (https://warmup-api.zerobounce.net). The validation key above is not accepted there, so the Warmup tools need a second key:

{
  "mcpServers": {
    "zerobounce": {
      "command": "zerobounce-mcp",
      "args": ["--api-key=YOUR_API_KEY", "--warmup-api-key=YOUR_WARMUP_API_KEY"]
    }
  }
}

ZEROBOUNCE_WARMUP_API_KEY works in place of the flag, the same way ZEROBOUNCE_API_KEY does, and the flag wins when both are set.

The Warmup key is optional. Leave it out and the 25 warmup_* tools are not advertised at all, so a client never sees a tool that cannot work. Supply it and the server exposes 75 tools instead of 50.

In HTTP mode the Warmup key is a per-request header, X-ZeroBounce-Warmup-Api-Key — see Your own HTTP server.

--warmup-url (or ZEROBOUNCE_WARMUP_API_URL) points the Warmup client at a different host, which is how the test suite reaches a stub. There is no regional Warmup host: warmup-api-us and warmup-api-eu do not resolve, so only an explicit https:// URL is accepted and shorthands such as us are refused.

MCP Client Configuration

Most MCP-compatible clients use the same basic configuration shape. A minimal example looks like:

{
  "mcpServers": {
    "zerobounce": {
      "command": "zerobounce-mcp",
      "args": ["--api-key=YOUR_API_KEY"]
    }
  }
}

Alternatively, supply the key through the ZEROBOUNCE_API_KEY environment variable instead of the flag:

{
  "mcpServers": {
    "zerobounce": {
      "command": "zerobounce-mcp",
      "env": { "ZEROBOUNCE_API_KEY": "YOUR_API_KEY" }
    }
  }
}

The --api-key flag takes precedence when both are set.

Command-line options

zerobounce-mcp --help (-h) and --version (-v) print and exit; neither needs a key. The key can also be given as -k <key> (same as --api-key). An unknown option or a stray argument is refused with Unknown argument: ... and the server does not start, so a misspelt --api-ky is never silently ignored.

Referencing an existing environment variable

Some clients let you reference a variable that already exists in their own environment, rather than writing the key into the config file:

{
  "mcpServers": {
    "zerobounce": {
      "command": "zerobounce-mcp",
      "env": { "ZEROBOUNCE_API_KEY": "${ZEROBOUNCE_API_KEY}" }
    }
  }
}

⚠️ This only works if the variable is present in the environment of the client process itself — not merely in your shell. A desktop client started from a macOS Dock icon, Spotlight, or a Windows Start-menu shortcut does not read ~/.zshrc, ~/.bashrc, or ~/.profile, so an export placed there will be invisible to it.

When the variable is missing, some clients pass the unresolved text ${ZEROBOUNCE_API_KEY} through as the key. That value is non-empty, so this server accepts it and starts normally: the client reports the server as connected and lists every tool, but each API call fails with api_key is invalid. The symptom looks like an expired key or a ZeroBounce outage, while the actual cause is that the reference was never expanded.

To confirm, check whether the variable is really visible to GUI applications:

launchctl getenv ZEROBOUNCE_API_KEY   # macOS; empty output means it is not set

On macOS you can publish it to the GUI session, expanding the value through an interactive shell so it does not silently resolve to an empty string:

zsh -ic 'launchctl setenv ZEROBOUNCE_API_KEY "$ZEROBOUNCE_API_KEY"'

Restart the client afterwards — it only inherits the variable if it is launched after the change. Note that launchctl setenv does not survive a reboot; make it permanent with a login LaunchAgent, or avoid the problem entirely by writing the key literally into the config as shown above.

Select your client below for detailed, client-specific setup steps:

  • Cursor plugin – Hosted MCP and the zerobounce skill (import this repo under Customize → Plugins)

  • Cursor – Manual MCP config, including self-hosted @zerobounce/mcp

  • VS Code – Configure ZeroBounce MCP for Visual Studio Code

  • Other / generic clients – Configure ZeroBounce MCP for Claude Desktop, Continue, Zed, and others

Regional API hosts

ZeroBounce serves the main API from three hosts. Pick one with --url, or with the ZEROBOUNCE_API_URL environment variable:

zerobounce-mcp --url us      # https://api-us.zerobounce.net/v2
zerobounce-mcp --url eu      # https://api-eu.zerobounce.net/v2
zerobounce-mcp               # https://api.zerobounce.net/v2 (default)

An explicit https:// URL is also accepted, which is how you point the server at a test double. A non-https or malformed URL is refused outright rather than quietly replaced with production, so the server never sends your key to a host you did not choose.

This setting applies to the main API only. There is no regional bulk or warmup host, so the bulk file jobs, the List Evaluator, the Inbox Placement Tester and the Warmup API are unaffected by it.

In HTTP mode the host is fixed when the server starts and cannot be set per request: the API key arrives from the caller, so a request that could also choose the host could point that key at a server of its own choosing.

Your own HTTP server

The server can also run as a stateless Streamable HTTP endpoint, for hosting it on your own infrastructure or a remote MCP platform. (To use ZeroBounce's own hosted server instead, see Connect to the hosted server.)

npm run build
PORT=3000 node dist/index.js --http
  • MCP endpoint: POST /mcp. A browser GET returns 405 Method Not Allowed, which is expected.

  • Health check: GET /health

  • Enable it with --http or MCP_TRANSPORT=http. The port comes from --port or PORT (default 3000).

  • The server binds to 127.0.0.1 by default, so it is only reachable from the same machine. In a container or on a hosting platform, terminate HTTPS at a trusted proxy, set MCP_TLS_TERMINATED=true, and bind all interfaces with --host 0.0.0.0 or MCP_HOST=0.0.0.0. Keep the connection between the proxy and this HTTP listener on a trusted private network.

  • The Host header must name the server: the loopback names for a loopback bind, the bind address itself, or a name given with --allowed-host <name> (repeatable) or MCP_ALLOWED_HOSTS (comma-separated). A cross-origin Origin header is refused with 403. This blocks DNS-rebinding attacks from web pages. On a wildcard bind (0.0.0.0) set your public host name this way; without it the server accepts any Host and logs a warning.

  • A repeated X-ZeroBounce-Api-Key, X-ZeroBounce-Warmup-Api-Key or Authorization header, or an X-ZeroBounce-Api-Key that differs from the bearer token, is refused with 400.

In HTTP mode each caller supplies their own ZeroBounce API key on every request, either as X-ZeroBounce-Api-Key: <key> or Authorization: Bearer <key>. ZEROBOUNCE_API_KEY and --api-key are ignored, so a hosted deployment never spends a shared key's credits. A request without a key is rejected with 401.

A caller who also wants the Warmup tools adds X-ZeroBounce-Warmup-Api-Key: <warmup key>. That key is a credential in its own right, so it travels per request exactly like the validation key: ZEROBOUNCE_WARMUP_API_KEY and --warmup-api-key are ignored in HTTP mode, and a key is never carried over from one request to the next. A request that omits it simply gets a server with no warmup_* tools; the validation tools still work.

{
  "mcpServers": {
    "zerobounce": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "X-ZeroBounce-Api-Key": "your_api_key_here",
        "X-ZeroBounce-Warmup-Api-Key": "your_warmup_api_key_here"
      }
    }
  }
}

Deploying from GitHub

Most hosted MCP platforms that build from a GitHub repository need these settings:

Setting

Value

Repository / Branch

zerobounce/zerobounce-mcp / main

Runtime / Preset

Node.js (MCP TypeScript SDK)

Repository Root Directory

(empty)

Build Command

npm ci && npm run build

Start Command

node dist/index.js --http --host 0.0.0.0

Port

3000

Environment Variables

MCP_TLS_TERMINATED=true (required; set PORT only if you change the port)

The server refuses to bind anything but loopback (127.0.0.1, ::1 or localhost) unless MCP_TLS_TERMINATED=true is set, and exits with Non-loopback HTTP binding requires MCP_TLS_TERMINATED=true and a trusted TLS-terminating proxy. Set it only when the platform terminates HTTPS in front of the server, because every request carries a caller's API key.

Tools

The ZeroBounce MCP server provides the following tools, organized by category.

Tool names, titles and annotations match the hosted ZeroBounce MCP server (mcp.zerobounce.net), so a model sees the same tools whichever server it is connected to. Every tool carries a title and readOnlyHint / destructiveHint / idempotentHint / openWorldHint annotations, and its description says when to use it and whether it spends credits (CREDITS:) or changes the account (WRITE:). Tools that delete or overwrite data (bulk file deletes, delete_filter, delete_inbox_placement_test, and the warmup updates and deletes) are marked destructiveHint: true, so clients ask before calling them.

Two endpoints are deliberately not exposed, as on the hosted server: setting the Inbox Placement webhook (it applies to the whole API key and is set in the ZeroBounce dashboard), and the Warmup API's SMTP configuration test (it takes the mailbox's SMTP password, which would pass through the conversation).

Validation Tools

validate (alias validate_email)

Validate a single email address. Returns status, sub-status and hygiene fields. Optional: ipAddress, timeout (3-60 seconds), activityData, verifyPlus, domainInfo (adds domain_website_exists and the WHOIS domain_registrant_company_name) and usePost.

validate_batch

Validate multiple email addresses in batch. More efficient for validating multiple emails at once.

Account Tools

get_credits (alias get_account_credits)

Get the number of credits remaining in your ZeroBounce account.

get_api_usage

Get API usage statistics for a date range. Shows validation counts by status and sub-status.

Bulk Validation File Tools

send_file

Send a CSV file for bulk email validation. Takes fileContent and fileName, plus the optional returnUrl, hasHeaderRow (sent as false when left out), removeDuplicate, allowPhase2 and the 0-based column indexes emailAddressColumn, firstNameColumn, lastNameColumn, genderColumn and ipAddressColumn. A returnUrl, when given, must be an HTTPS callback URL on a public host (port 443, no credentials, no private or special-purpose address); the server refuses anything else before the request. Returns a file ID for tracking.

file_status

Get the status of a bulk validation file upload.

get_file

Get the results of a completed bulk validation file. Optional downloadType (phase_1, phase_2 or combined) and activityData. scoring_get_file takes downloadType too.

delete_file

Delete a bulk validation file from your account.

AI Scoring Tools

scoring_send_file

Send a CSV file for bulk AI email scoring. Takes fileContent and fileName, plus the optional returnUrl, hasHeaderRow (sent as false when left out), removeDuplicate and the 0-based emailAddressColumn. returnUrl follows the same rules as for send_file: HTTPS, port 443, public host, no credentials. Returns a file ID for tracking.

scoring_file_status

Get the status of a bulk AI scoring file upload.

scoring_get_file

Get the results of a completed bulk AI scoring file.

scoring_delete_file

Delete a bulk AI scoring file from your account.

score_email

Score a single email address in real time (/v2/scoring). Returns the address and its numeric score. Set usePost to send the key and address form-encoded over POST instead of in the query string.

Email Finder Tools

find_email_format

Find an email address based on domain, name, and/or company.

send_email_finder_file

Send a CSV file for bulk email finding. Takes fileContent and fileName, plus the 0-based column indexes domainColumn, firstNameColumn, middleNameColumn, lastNameColumn and fullNameColumn, and hasHeaderRow (sent as false when left out). firstNameColumn or fullNameColumn is required: the API needs a name to work from. The endpoint takes no callback URL. Returns a file ID for tracking.

email_finder_file_status

Get the status of a bulk email finder file upload.

email_finder_get_file

Get the results of a completed bulk email finder file.

email_finder_delete_file

Delete a bulk email finder file from your account.

Domain Search Tools

find_domain

Search for email addresses in a domain.

send_domain_search_file

Send a CSV file for bulk domain search. Takes fileContent and fileName, plus the 0-based domainColumn and hasHeaderRow (sent as false when left out). The endpoint takes no callback URL. Returns a file ID for tracking.

domain_search_file_status

Get the status of a bulk domain search file upload.

domain_search_get_file

Get the results of a completed bulk domain search file.

domain_search_delete_file

Delete a bulk domain search file from your account.

Activity Data Tools

get_activity

Get activity data for an email address to see if it has been active recently.

Warmup Tools

These 25 tools cover every documented operation of the Warmup API except test_smtp_configuration, which takes an SMTP password. They are only advertised when a Warmup API key is configured — see Warmup API key. They never use the validation key.

Sending accounts

warmup_list_sending_accounts

List every sending account belonging to the Warmup key's team.

warmup_get_sending_account

Get one sending account by fromAddress.

warmup_add_sending_account

Add a from-address to warmup. onboardingModel: "self_managed" runs your own mailbox and requires engagementRuleId (0-4). "zb_managed" has ZeroBounce provision the mailbox and takes emailContent and managedSending instead; it rejects engagementRuleId.

warmup_update_sending_account

Change an account's engagementRuleId (0-4), statusId (0-8; 4 Paused, 5 Disabled) and autoEnable flag. autoEnable: true is accepted only for an account that is not active.

warmup_delete_sending_account

Remove a sending account. Destructive: the account and its warmup history go with it.

warmup_change_from_address

Move an account and its history from oldFromAddress to newFromAddress. Despite the /smtp-credentials path it uses, no SMTP credentials are stored.

warmup_list_from_addresses

List the registered from-addresses. Optional searchFrom (letters, digits and . - _ @ + only), offset and limit.

Engagement rules

warmup_get_engagement_rules

The rule catalogue: -1 Custom, 0 Default, 1 Slow Pace, 2 Repair, 3 Boost, 4 Protect.

warmup_set_engagement_rule

Set a standard rule (ruleId 0-4) on an address (cFrom).

warmup_get_custom_engagement

An address's custom rule, including can_update and the remaining_seconds of the cooldown.

warmup_create_custom_engagement

Create a custom rule from replyPct (5-45), importantPct (5-40) and clickPct (0-70, and at most importantPct x 1.75). Starts a 7-day cooldown before the rule can be updated.

warmup_update_custom_engagement

Update a custom rule. During the 7-day cooldown the API answers with HTTP 429.

warmup_delete_custom_engagement

Delete a custom rule and fall back to a standard rule (engagementRuleId 1-4).

Seeds, progress and statistics

warmup_get_seeds

The seed list.

warmup_download_seeds

The seed list as CSV text (columns seed,provider), returned as-is rather than wrapped in JSON.

warmup_get_seed_count

The number of seeds.

warmup_get_progress_today

Today's warmup progress.

warmup_get_sent_today

Messages sent today.

warmup_get_emails_per_day

The current daily sending volume.

warmup_get_statistics

Statistics for a fromAddress. An address with no history returns zeros.

warmup_get_statistics_per_day

Daily statistics between startDate and endDate (YYYY-MM-DD), inclusive.

warmup_get_statistics_detailed

Detailed statistics for an address (cFrom).

warmup_download_statistics

An address's statistics as CSV text, returned as-is rather than wrapped in JSON.

warmup_get_from_address_statistics

Statistics for one from-address.

Diagnostics

warmup_check_domain_dmarc

SPF, DKIM and DMARC status of a from-address's domain, with an optional dkimSelector.

fromAddress must be a full email address such as sender@example.com. The live API answers Please provide a valid email address for a bare domain, although the public docs describe a domain. A bare domain is rejected before the call is made.

Inbox Placement Tester Tools

The Inbox Placement Tester (bulkapi.zerobounce.net/api/ipt) reports where a campaign actually lands at each mailbox provider: inbox, spam, or missing. You create a test, send your campaign to the seed addresses it returns, then read the results back.

This API authenticates with an Authorization: Bearer header rather than an api_key parameter, so the key never appears in a request URL. It uses the same ZeroBounce API key as the rest of the server; no extra configuration is needed.

get_inbox_placement_providers

List the seed providers and their seed addresses available for new tests.

get_inbox_placement_test_types

List the supported test types and which one is the default.

create_inbox_placement_test

Start a test. Takes name (unique, at most 64 characters) and optionally testType (1 = Email, which also requires senderEmail; 2 = Unique ID; 3 = Auto Alias), the seeds to use (providerIds, seedIds, or providers as [{ id, maxSeeds }] to cap seeds per provider). Results also go to the API key's saved webhook, which is set in the ZeroBounce dashboard.

get_inbox_placement_test

Get one test and its placement results by testId.

list_inbox_placement_tests

List tests, newest first. Filters: status (running or finished), createdAfter and createdBefore (ISO 8601), page, and pageSize (1 to 100).

delete_inbox_placement_test

Delete a finished test. A running test cannot be deleted.

get_inbox_placement_webhook

Get the webhook URL finished results are posted to for this API key. No tool changes it: set, change or remove it in the ZeroBounce dashboard.

List Evaluator Tools

send_list_evaluator_file

Upload a CSV to the List Evaluator and get back a file_id.

get_list_evaluator_result

Fetch the evaluation for a file_id.

send_evaluated_file

Submit a finished evaluation for bulk validation. Takes the List Evaluator's fileId -- despite what the public docs show, this endpoint is not a file upload, and an upload is rejected with "file_id: This field is required".

S3 and SFTP/FTP Bulk Tools

These run a bulk job over a file that already sits in your storage, so nothing is uploaded through the MCP server. The bucket, server, path and protocol all come from your ZeroBounce account settings.

Every job tool takes the same arguments:

Argument

Required

Notes

fileName

yes

Object key (S3) or path on the server (SFTP/FTP)

returnUrl

yes

HTTPS callback notified when the job finishes. The API refuses a job without one. Only use a URL you control: it receives your bulk results. Refused: credentials in the URL, a port other than 443, whitespace or control characters, and loopback, private, link-local, metadata or other special-purpose addresses (IPv6 forms that embed an IPv4 address included). Host names are not resolved: ZeroBounce's servers make the callback

hasHeaderRow

no

Defaults to false

removeDuplicates

no

Omitted when not given

list_s3files

List the files in your S3 bucket. Optional bucket and search filters.

validate_s3file / score_s3file / email_finder_s3file / domain_search_s3file

Run bulk validation, AI scoring, email finder or domain search over an object in your S3 bucket.

validate_sftpfile / score_sftpfile / email_finder_sftpfile / domain_search_sftpfile

The same four jobs over a file on your SFTP/FTP server.

export_s3file

Export a completed bulk job to S3. Takes fileId and an optional exportBucket; without a bucket the API uses the output bucket configured on your account.

export_sftpfile

Export a completed bulk job back to your SFTP/FTP server. Takes fileId and an optional exportPath -- a path, not a bucket; without it the API uses the export path configured on your account.

Filter Tools

add_filter

Add a custom allow or block list filter. Takes rule, target, and value.

list_filters

List the custom filters on the account. Uses GET by default; set usePost to send POST.

delete_filter

Delete a custom filter. Takes the same rule, target, and value that created it.

Tool Availability

On the hosted server, a connection lists the tools you approved on the consent page. When you run the package yourself:

The ZeroBounce SDK (@zerobounce/zero-bounce-sdk 5.0.1) is bundled into dist/index.js, so every tool is available in every install and nothing depends on an SDK on your machine. The tool list changes only with the keys you supply: the 25 Warmup tools need a Warmup API key (see above), so a server started without one exposes 50 tools. As a safety net the server still hides a tool whose SDK method is missing from the bundle, rather than advertise one it cannot run. Call the MCP tools/list method to see exactly what your server exposes.

Resources

The server provides the following resources:

zerobounce://config

Current ZeroBounce API configuration: the main API base URL and whether a validation key is configured, plus the Warmup base URL and whether a Warmup key is configured. Keys themselves are never included.

Usage Examples

Basic Email Validation

Validate a single email:

Validate the email address "test@example.com"

Validate with IP address for better accuracy:

Validate "test@example.com" from IP address "192.168.1.1"

Validate multiple emails in batch:

Check if these emails are valid: ["user1@example.com", "user2@example.com", "user3@example.com"]

Account Management

Check remaining credits:

How many credits do I have left in my ZeroBounce account?

Get usage statistics:

Show me my ZeroBounce API usage for January 2024

Show usage from specific dates:

Get my API usage from 2024-01-01 to 2024-01-31

AI Email Scoring

Score emails via CSV upload:

Use AI to score the quality and deliverability of these email addresses and return the results as a CSV: [paste CSV content]

Email Finding

Find an email by name and domain:

Find the email for John Doe at example.com

Find email by name and company:

Find the email for John Doe at Example Corp (example.com)

Search for emails in a domain:

Search for all email addresses at example.com

Search with filters:

Find emails for people named John at example.com

Activity Data

Check email activity:

Check if test@example.com has been active recently

Bulk Operations

Upload a file for bulk validation:

Bulk validate the emails in this CSV file: [paste CSV content]

Check bulk validation status:

Check the status of my bulk validation file abc123

Get bulk validation results:

Get the results for my completed bulk validation file abc123

Status Values

validate_email and validate_batch return one of these status values, as listed in the ZeroBounce status codes reference:

  • valid: Email address is valid and safe to email

  • invalid: Email address is invalid; remove it from your list

  • catch-all: The domain accepts mail for any address, so the mailbox cannot be confirmed

  • spamtrap: Email address is believed to be a spam trap

  • abuse: Email address belongs to someone known to report mail as spam

  • do_not_mail: Email address you should avoid mailing (role-based, disposable, toxic, and so on)

  • unknown: The address could not be validated, for example because the mail server is offline

Sub-Status Values

sub_status explains a result further. It is empty when there is nothing to add, and not every invalid or unknown result has one.

status

sub_status values

valid

alias_address, leading_period_removed, alternate, gold, accept_all, role_based_accept_all, ai_agent_mailbox, allowed

invalid

does_not_accept_mail, failed_syntax_check, possible_typo, mailbox_not_found, no_dns_entries, mailbox_quota_exceeded, unroutable_ip_address

catch-all

ai_agent_mailbox

do_not_mail

role_based, disposable, role_based_catch_all, mx_forward, global_suppression, possible_trap, toxic, blocked

unknown

antispam_system, exception_occurred, failed_smtp_connection, forcible_disconnect, greylisted, mail_server_did_not_respond, mail_server_temporary_error, timeout_exceeded

allowed and blocked come from your own custom filters: an address that matches an allow rule is returned as valid / allowed, and one that matches a block rule as do_not_mail / blocked.

Security Best Practices

With the hosted server no API key leaves your ZeroBounce account. Grant only the permissions the assistant needs, and disconnect it (or connect again with fewer tools) when you no longer use it.

Protecting Your API Key (self-hosted)

Your ZeroBounce API key is sensitive and should be protected:

  1. Never Commit API Keys: Add configuration files with API keys to .gitignore

    mcp.json
    .env
  2. Use Separate Keys: Use different API keys for development, staging, and production

  3. Rotate Keys Regularly: Periodically rotate your API keys from the ZeroBounce dashboard

  4. Monitor Usage: Regularly check your API usage to detect unauthorized access

Development

For local development on this MCP server:

  • Install dependencies:

    npm install
  • Build the project:

    npm run build
  • Install the CLI globally (optional, for local testing):

    npm install -g .

    After this, you can use the zerobounce-mcp command in your MCP client config, for example:

    {
      "mcpServers": {
        "zerobounce": {
          "command": "zerobounce-mcp",
          "args": ["--api-key=YOUR_API_KEY"]
        }
      }
    }
  • Run the tests:

    npm run typecheck && npm run build && npm test

    npm test runs test-http.js, test/client-key.test.ts, test/cli.test.ts and test/redaction.test.ts. They run offline against a fake API, need no API key, and check routing, auth, every tool, per-request API key isolation, that no object holds the key in an inspectable property, and the command-line flags.

    The stdio test against the live ZeroBounce API is separate and spends credits. Run it with a real key (a placeholder key is blocked by Cloudflare rather than rejected by the API):

    npm run test:live -- --api-key="$ZEROBOUNCE_API_KEY"

Error Handling

The server handles errors gracefully and returns descriptive error messages:

Common Errors

Error

Cause

Solution

Missing API key

API key not provided

Add the --api-key argument or set ZEROBOUNCE_API_KEY

Invalid API key

API key is incorrect or expired

Verify your API key in the ZeroBounce dashboard

api_key is invalid on every call, though the server connects

Config used ${ZEROBOUNCE_API_KEY} but the client could not expand it, so the literal placeholder was sent as the key

See Referencing an existing environment variable — publish the variable to the client's environment, or write the key literally into the config

Network errors

Cannot connect to ZeroBounce API

Check your internet connection and firewall settings

Rate limiting

Too many requests

Wait and retry, or upgrade your ZeroBounce plan

Invalid email format

Email address format is invalid

Check the email address format

Invalid date format

Date not in YYYY-MM-DD format

Use the correct date format (e.g., "2024-01-31")

Insufficient credits

Not enough credits in account

Add credits to your ZeroBounce account

File not found

Bulk validation file ID is invalid

Verify the file ID from the upload response

Error Response Format

A tool that fails returns an ordinary MCP tool result with isError set, and the message as text prefixed with Error: :

{
  "content": [{ "type": "text", "text": "Error: api_key is invalid" }],
  "isError": true
}

Messages longer than 1000 characters are truncated, and an HTML error page from the API is reported as a one-line summary instead of the page itself.

In HTTP mode, a request rejected before it reaches a tool (a missing API key, or a method other than POST) gets a JSON-RPC error with the matching HTTP status (401, 405):

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Method not allowed." },
  "id": null
}

License

MIT. See LICENSE.


Made with ❤️ for the MCP community

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    • ZeroBounce lets you verify and validate email addresses in ChatGPT. Ask it to check one email address, a batch of addresses or a whole list file, and it returns a result for each address that ChatGPT can explain in plain language. It can also find business email addresses and score email quality with AI. ZeroBounce validation checks the syntax of the address, checks the domain's DNS and MX records, and runs an SMTP check with the domain's mail server. Results can flag disposable (temporary) addresses, role-based addresses such as info@ or sales@, catch-all domains, addresses ZeroBounce believes to be spam traps, abuse addresses and toxic addresses. When an address looks mistyped, the result can include a suggested correction. Each address gets a status: valid, invalid, catch-all, unknown, spamtrap, abuse or do_not_mail. Where one applies, a sub-status gives the reason, such as mailbox_not_found, disposable or role_based. Results can also show whether the address uses a free email provider, whether the domain is catch-all, its MX record, the SMTP provider, the domain age in days, the owner's first name, last name and gender when available, and when the check was processed. If you provide an IP address, results can include its country, region, city and zip code. You can also set a timeout, turn on Verify+, or add website availability and WHOIS company details for the domain. Beyond single checks: - Validate whole lists: send a CSV or TXT file, track its progress, download the results and delete the file - Score emails with AI: get a quality score from 0 to 10 for one address or a whole file, which helps with catch-all addresses - Find a business email address from a person's name and a domain or company, with a high, medium or low confidence level - Search a domain or company for the email formats it is likely to use, one at a time or from a file - Check activity data: how recently an inbox was active and when ZeroBounce first saw it - Manage allow and block rules for specific emails, domains, MX records or TLDs - Estimate the risk level of a list before you validate it - Validate, score and export files stored in Amazon S3 or on an SFTP/FTP server - Run inbox placement tests, manage warmup sending accounts and check SPF, DKIM and DMARC records - Check your remaining credits and your API usage by date range, status and sub-status Ask ChatGPT to explain any result, or to sort your checked addresses into keep, review and remove based on their status and sub-status. Common uses: - Checking an email from a signup or lead form before you add it to your list - Cleaning a full list before a newsletter, outreach sequence or product launch - Checking one contact before you send an important message - Spotting typos, disposable addresses and role-based addresses before they reach your list - Finding a business email address for a contact you are authorized to reach Large lists: send the list as a CSV or TXT file for bulk validation instead of pasting addresses into the chat. Check your remaining credits first. Before ZeroBounce checks an address, searches for a contact or processes a file, ChatGPT asks you to approve sharing the data. You can allow once, allow for the conversation, always allow or deny. Only validate addresses you are authorized to process. Only search for contacts and domains you are authorized to research. Limitations: results reflect each address at the time of the check and do not guarantee delivery or inbox placement. Catch-all and unknown results cannot be fully confirmed. Found email addresses, domain formats and AI scores are estimates, not confirmation that a mailbox exists. Some features, such as activity data, inbox placement tests and warmup, depend on your ZeroBounce account plan. The plugin does not send your emails or campaigns and does not diagnose past bounces.

      https://mcp.zerobounce.net/mcp
    • Email verification and domain intelligence for AI agents, including single and bulk email checks.

      https://manhourplan.com/mcp
    • Free SPF, DKIM, DMARC, blacklist, MX and bounce checks for any domain, as MCP tools for AI agents.

      https://outboundauth.com/mcp
    • Email verification and domain intelligence for AI agents. MX, RDAP, SSL checks. 25 free credits.

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows interaction with the ZeroBounce email validation service, enabling users to validate individual emails, check account credits, and perform bulk validations.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Email-deliverability tools for AI agents — 12 MCP tools across email verification, DNSBL across 50 zones, SPF/DKIM/DMARC analysis, spam-trap scoring, domain intelligence, and email finder. Free tier with no credit card.
      12
      35 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI agents to validate email addresses and send emails via SMTP with zero external dependencies.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides email validation and domain configuration auditing tools for AI assistants, enabling single address checks, bulk list cleaning, SPF verification, and full mail setup grading (A-F) with actionable fixes.
      4
      40 npm
      MIT