README.md•5.25 kB
# AtData SafeToSend MCP Server
A Model Context Protocol (MCP) server that provides email verification services using AtData's SafeToSend API. This server allows you to verify email addresses to filter out invalid and high-risk ones, resulting in higher open rates, clicks, and conversions.
https://docs.atdata.com/reference/safe-to-send
## Features
- **Email Verification**: Verify individual email addresses using AtData's SafeToSend API
- **Batch Verification**: Verify multiple email addresses at once with summary statistics
- **Comprehensive Error Handling**: Detailed error messages for different failure scenarios
- **Environment Variable Support**: Secure API key management through environment variables
- **Rate Limiting Awareness**: Proper handling of API rate limits
## Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd atdata-mcp-server
```
2. Install dependencies using uv (recommended) or pip:
```bash
# Using uv
uv sync
# Using pip
uv pip install .
```
## Setup
### Get AtData API Key
1. Sign up for an AtData account at [https://atdata.com](https://atdata.com)
2. Obtain your API key from the AtData dashboard
3. Set up your API key as an environment variable:
```bash
export ATDATA_API_KEY="your-api-key-here"
```
Or create a `.env` file in the project root:
```
ATDATA_API_KEY=your-api-key-here
```
## Usage
### Running the Server
#### Method 1: Direct Python execution
```bash
python server.py
```
#### Method 2: Using FastMCP CLI
```bash
fastmcp run server.py
```
#### Method 3: Install for Claude Desktop
```bash
fastmcp install server.py
```
#### Using with uv
If you're using uv, you can also run the server with:
```json
{
"mcpServers": {
"atdata-email-verification-mcp-server": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/your/atdata-email-verification-mcp-server",
"env": {
"ATDATA_API_KEY": "your_api_key_here"
}
}
}
}
```
### Available Tools
#### 1. `verify_email`
Verify a single email address.
**Parameters:**
- `email` (string, required): The email address to verify
- `api_key` (string, optional): AtData API key (uses environment variable if not provided)
**Example:**
```python
{
"email": "user@example.com",
"api_key": "your-api-key" # Optional if ATDATA_API_KEY is set
}
```
**Response:**
```python
{
"success": True,
"email": "user@example.com",
"verification_result": {
"email": "user@example.com",
"status": "valid",
"deliverable": True,
"risk_level": "low",
# Additional verification details from AtData API
}
}
```
#### 2. `batch_verify_emails`
Verify multiple email addresses in batch.
**Parameters:**
- `emails` (array of strings, required): List of email addresses to verify
- `api_key` (string, optional): AtData API key (uses environment variable if not provided)
**Example:**
```python
{
"emails": ["user1@example.com", "user2@domain.com", "invalid@email"],
"api_key": "your-api-key" # Optional if ATDATA_API_KEY is set
}
```
**Response:**
```python
{
"results": [
{
"success": True,
"email": "user1@example.com",
"verification_result": { /* verification details */ }
},
{
"success": True,
"email": "user2@domain.com",
"verification_result": { /* verification details */ }
},
{
"error": "Bad request. Please check the email format.",
"email": "invalid@email",
"status_code": 400
}
],
"summary": {
"total": 3,
"successful": 2,
"failed": 1,
"success_rate": 66.67
}
}
```
## Error Handling
The server provides comprehensive error handling for various scenarios:
- **Missing API Key**: Returns error when no API key is provided
- **Authentication Errors**: Handles invalid API keys (401 status)
- **Bad Requests**: Handles invalid email formats (400 status)
- **Rate Limiting**: Handles API rate limit exceeded (429 status)
- **Network Issues**: Handles connection errors and timeouts
- **Unexpected Errors**: Catches and reports any unexpected exceptions
## API Documentation
This server is based on the AtData SafeToSend API. For more details about the underlying API, see:
- [AtData SafeToSend API Documentation](https://docs.atdata.com/reference/safe-to-send)
## Development
### Project Structure
```
atdata-mcp-server/
├── src/
│ └── server.py # Main MCP server implementation
├── pyproject.toml # Project configuration and dependencies
├── uv.lock # Locked dependencies
└── README.md # This file
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Support
For issues related to:
- **This MCP Server**: Open an issue in this repository
- **AtData API**: Contact AtData support or check their documentation
- **FastMCP Framework**: Check the [FastMCP documentation](https://github.com/jlowin/fastmcp)