ZeroBounce MCP Server

A comprehensive Model Context Protocol (MCP) server that provides full-featured email validation, verification, and intelligence capabilities through ZeroBounce's API. This server enables AI coding assistants and MCP-compatible clients to validate email addresses, find emails, score email quality, search domains, and much more.

Features

Core Capabilities

Email Validation: Validate single or multiple email addresses with detailed results
Batch Processing: Efficiently process large volumes of emails via CSV upload
AI Scoring: Evaluate email quality and deliverability using AI via bulk CSV file uploads
Email Finder: Find email addresses based on name and company/domain
Domain Search: Search for all email addresses in a domain
Activity Data: Check if an email address has been recently active
Credit Management: Monitor remaining credits in your ZeroBounce account
Usage Analytics: Get detailed API usage reports for any date range

Key Benefits

🚀 Fast Integration: Quick setup with MCP-compatible clients
🔒 Secure: API key management with environment variable support
📊 Broad Coverage: Access to all major ZeroBounce API endpoints exposed by the official Node SDK and suitable for MCP tools
🎯 Accurate: Industry-leading email validation accuracy
🔄 Real-time: Instant validation and scoring results

Quick Start

Install the MCP server globally

npm install -g @zerobounce/mcp

This will install the zerobounce-mcp command globally.

Get your ZeroBounce API key from the ZeroBounce Dashboard
Add to your MCP client (Cursor, VS Code, Claude Desktop, etc.):

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

Start using it in your AI assistant:

Validate the email address "[email protected]"

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.

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"]
    }
  }
}

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

Cursor – Configure ZeroBounce MCP for Cursor IDE
VS Code – Configure ZeroBounce MCP for Visual Studio Code
Other / generic clients – Configure ZeroBounce MCP for Claude Desktop, Continue, Zed, and others

Tools

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

Validation Tools

`validate_email`

Validate a single email address using ZeroBounce API. Returns detailed validation results including status, sub-status, and additional metadata.

`validate_batch`

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

Account Tools

`get_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

`bulk_validate_send_file`

Send a CSV file for bulk email validation. Returns a file ID for tracking.

`bulk_validate_file_status`

Get the status of a bulk validation file upload.

`bulk_validate_get_file`

Get the results of a completed bulk validation file.

`bulk_validate_delete_file`

Delete a bulk validation file from your account.

AI Scoring Tools

`bulk_ai_scoring_send_file`

Send a CSV file for bulk AI email scoring. Returns a file ID for tracking.

`bulk_ai_scoring_file_status`

Get the status of a bulk AI scoring file upload.

`bulk_ai_scoring_get_file`

Get the results of a completed bulk AI scoring file.

`bulk_ai_scoring_delete_file`

Delete a bulk AI scoring file from your account.

Email Finder Tools

`find_email`

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

Note: Bulk Email Finder file operations are not available via the official Node SDK and are not exposed as MCP tools.

Domain Search Tools

`domain_search`

Search for email addresses in a domain.

Note: Bulk Domain Search file operations are not available via the official Node SDK and are not exposed as MCP tools.

Activity Data Tools

`get_activity_data`

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

Limitations and Non-Supported Endpoints

Custom filters / filter management: Not available via the official ZeroBounce Node SDK and therefore not exposed as MCP tools.
List Evaluator: The List Evaluator endpoint is not supported by the Node SDK and is not implemented in this MCP server.
Per-email AI scoring tool: AI scoring is currently supported only via bulk CSV file operations, not as a single-email scoring tool.

Resources

The server provides the following resources:

`zerobounce://config`

Current ZeroBounce API configuration (base URL and whether API key is configured).

Usage Examples

Basic Email Validation

Validate a single email:

Validate the email address "[email protected]"

Validate with IP address for better accuracy:

Validate "[email protected]" from IP address "192.168.1.1"

Validate multiple emails in batch:

Check if these emails are valid: ["[email protected]", "[email protected]", "[email protected]"]

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)

Domain Search

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 [email protected] 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

ZeroBounce returns the following status values:

valid: Email address is valid
invalid: Email address is invalid
catchall: Domain accepts all emails (catch-all)
do_not_mail: Email address is on a do-not-mail list
spamtrap: Email address is a spamtrap
abuse: Email address is associated with abuse
unknown: Unable to determine validity

Sub-Status Values

Common sub-status values include:

toxic: Email address contains toxic words
disposable: Email address is from a disposable email service
role_based: Email address is role-based (e.g., admin@, info@)
possible_trap: Email address might be a trap
global_suppression: Email address is on a global suppression list
timeout_exceeded: Validation timeout exceeded
mail_server_temporary_error: Temporary mail server error
mail_server_did_not_respond: Mail server did not respond
greylisted: Email address is greylisted
antispam_system: Blocked by antispam system
does_not_accept_mail: Domain does not accept mail
exception_occurred: Exception occurred during validation
failed_syntax_check: Email failed syntax check
mailbox_quota_exceeded: Mailbox quota exceeded
possible_typo: Possible typo in email address
unroutable_ip_address: Unroutable IP address
leading_period_removed: Leading period was removed
does_not_accept_mail_from_mailer_daemon: Does not accept mail from mailer daemon
address_is_blocked: Address is blocked
failed_antispam_check: Failed antispam check
mailbox_not_found: Mailbox not found
unroutable_mail_server: Unroutable mail server
invalid: Invalid email address
mail_server_did_not_respond_within_timeout_period: Mail server did not respond within timeout
address_failed_validation: Address failed validation
mailbox_storage_exceeded: Mailbox storage exceeded
mailbox_administratively_disabled: Mailbox administratively disabled
domain_not_found: Domain not found
address_is_on_a_global_suppression_list: Address is on a global suppression list

Security Best Practices

Protecting Your API Key

Your ZeroBounce API key is sensitive and should be protected:

Never Commit API Keys: Add configuration files with API keys to .gitignore
```
mcp.json
.env
```
Use Separate Keys: Use different API keys for development, staging, and production
Rotate Keys Regularly: Periodically rotate your API keys from the ZeroBounce dashboard
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"]
    }
  }
}

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 `--api-key` argument
Invalid API key	API key is incorrect or expired	Verify your API key in the ZeroBounce dashboard
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

Errors are returned in a structured format:

{
  "error": "Error type",
  "message": "Detailed error description",
  "details": "Additional context (if available)"
}

Made with ❤️ for the MCP community

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
dist		dist
docs		docs
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-mcp.js		test-mcp.js
tsconfig.json		tsconfig.json

zerobounce/zerobounce-mcp

Folders and files

Latest commit

History

Repository files navigation

ZeroBounce MCP Server

Features

Core Capabilities

Key Benefits

Quick Start

Getting Your API Key

MCP Client Configuration

Tools

Validation Tools

validate_email

validate_batch

Account Tools

get_credits

get_api_usage

Bulk Validation File Tools

bulk_validate_send_file

bulk_validate_file_status

bulk_validate_get_file

bulk_validate_delete_file

AI Scoring Tools

bulk_ai_scoring_send_file

bulk_ai_scoring_file_status

bulk_ai_scoring_get_file

bulk_ai_scoring_delete_file

Email Finder Tools

find_email

Domain Search Tools

domain_search

Activity Data Tools

get_activity_data

Limitations and Non-Supported Endpoints

Resources

zerobounce://config

Usage Examples

Basic Email Validation

Account Management

AI Email Scoring

Email Finding

Domain Search

Activity Data

Bulk Operations

Status Values

Sub-Status Values

Security Best Practices

Protecting Your API Key

Development

Error Handling

Common Errors

Error Response Format

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

`validate_email`

`validate_batch`

`get_credits`

`get_api_usage`

`bulk_validate_send_file`

`bulk_validate_file_status`

`bulk_validate_get_file`

`bulk_validate_delete_file`

`bulk_ai_scoring_send_file`

`bulk_ai_scoring_file_status`

`bulk_ai_scoring_get_file`

`bulk_ai_scoring_delete_file`

`find_email`

`domain_search`

`get_activity_data`

`zerobounce://config`

Packages