README.md•2.7 kB
# ZeroBounce MCP Server
This is a Model Context Protocol (MCP) server for interacting with the ZeroBounce email validation service. It uses the official [ZeroBounce Python API v2](https://github.com/zerobounce/zerobounce-python-api-v2) library.
## Features
- Validate individual email addresses
- Check your remaining API credits
- Upload files for bulk validation
- Check file status, retrieve, and delete bulk validation files
- Search for email patterns used by a domain
## Setup
### System Requirements
- Python 3.10+
- API key from ZeroBounce
### Installation
1. Clone this repository:
```bash
git clone https://github.com/avivshafir/zerobounce-mcp-server
cd zerobounce-mcp-server
```
2. Install the required dependencies:
```bash
pip install -r requirements.txt
```
3. Set up your environment variables:
Option 1: Using a .env file (recommended)
Create a .env file with your ZeroBounce API key:
```
ZEROBOUNCE_API_KEY=your_zerobounce_api_key
```
Option 2: Setting environment variables directly
```bash
export ZEROBOUNCE_API_KEY="your_zerobounce_api_key"
```
You can get your API key from your ZeroBounce account dashboard.
Add the following configuration to the `mcp.json` file, replacing the directory path with the actual path to where you've installed this server:
```json
{
"mcpServers": {
"zerobounce": {
"command": "python",
"args": ["/path/to/your/zerobounce-mcp-server/main.py"]
}
}
}
```
4. Restart Cursor to apply the changes
Now you can use the ZeroBounce MCP server directly within Cursor's AI assistant.
## Available Tools
The server provides the following tools:
1. `validate_email`: Validate a single email address
```
validate_email(email: str, ip_address: str = "") -> dict
```
2. `get_credits`: Check remaining credits in your ZeroBounce account
```
get_credits() -> dict
```
3. `upload_file`: Upload a file for bulk validation
```
upload_file(file_path: str, email_column: int, ...) -> dict
```
4. `check_file_status`: Check the status of a bulk validation file
```
check_file_status(file_id: str) -> dict
```
5. `get_file`: Get the results of a bulk validation
```
get_file(file_id: str) -> dict
```
6. `delete_file`: Delete a bulk validation file
```
delete_file(file_id: str) -> dict
```
7. `domain_search`: Search for email patterns used by a domain
```
domain_search(domain: str) -> dict
```
## Dependencies
- zerobounce-python-api-v2: The official ZeroBounce API library
- python-dotenv: For loading environment variables from .env file
- mcp: The Model Context Protocol library
- asyncio: For asynchronous operations