atdata-email-verification-mcp-server

🚀 AtData SafeToSend MCP 服务器

AtData SafeToSend MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它借助 AtData 的 SafeToSend API 提供电子邮件验证服务。使用该服务器，你可以对电子邮件地址进行验证，过滤掉无效和高风险的地址，从而提高邮件的打开率、点击率和转化率。

AtData SafeToSend API 文档

✨ 主要特性

• 单封邮件验证：利用 AtData 的 SafeToSend API 对单个电子邮件地址进行验证。
• 批量邮件验证：可一次性验证多个电子邮件地址，并提供汇总统计信息。
• 全面的错误处理：针对不同的失败场景给出详细的错误信息。
• 支持环境变量：通过环境变量安全地管理 API 密钥。
• 速率限制感知：妥善处理 API 速率限制。

📦 安装指南

1. 克隆此仓库：

git clone <repository-url>
cd atdata-mcp-server

2. 使用 uv（推荐）或 pip 安装依赖项：

# 使用 uv
uv sync

# 使用 pip
uv pip install .

📚 详细文档

获取 AtData API 密钥

1. 在 https://atdata.com 上注册 AtData 账户。
2. 从 AtData 控制台获取你的 API 密钥。
3. 将你的 API 密钥设置为环境变量：

export ATDATA_API_KEY="your-api-key-here"

或者在项目根目录下创建一个 .env 文件：

ATDATA_API_KEY=your-api-key-here

💻 使用示例

启动服务器

方法一：直接使用 Python 执行

python server.py

方法二：使用 FastMCP CLI

fastmcp run server.py

方法三：为 Claude Desktop 安装

fastmcp install server.py

使用 uv 启动

如果你使用的是 uv，也可以通过以下方式启动服务器：

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

可用工具

1. verify_email

验证单个电子邮件地址。 参数：

• email（字符串，必需）：要验证的电子邮件地址。
• api_key（字符串，可选）：AtData API 密钥（如果未提供，则使用环境变量）。

示例：

{
    "email": "user@example.com",
    "api_key": "your-api-key"  # 如果设置了 ATDATA_API_KEY，则可选
}

响应：

{
    "success": True,
    "email": "user@example.com",
    "verification_result": {
        "email": "user@example.com",
        "status": "valid",
        "deliverable": True,
        "risk_level": "low",
        # 来自 AtData API 的其他验证详情
    }
}

2. batch_verify_emails

批量验证多个电子邮件地址。 参数：

• emails（字符串数组，必需）：要验证的电子邮件地址列表。
• api_key（字符串，可选）：AtData API 密钥（如果未提供，则使用环境变量）。

示例：

{
    "emails": ["user1@example.com", "user2@domain.com", "invalid@email"],
    "api_key": "your-api-key"  # 如果设置了 ATDATA_API_KEY，则可选
}

响应：

{
    "results": [
        {
            "success": True,
            "email": "user1@example.com",
            "verification_result": { /* 验证详情 */ }
        },
        {
            "success": True,
            "email": "user2@domain.com", 
            "verification_result": { /* 验证详情 */ }
        },
        {
            "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
    }
}

🔧 技术细节

该服务器提供了全面的错误处理机制，以应对各种不同的场景：

• 缺少 API 密钥：当未提供 API 密钥时返回错误。
• 身份验证错误：处理无效的 API 密钥（401 状态）。
• 错误请求：处理无效的电子邮件格式（400 状态）。
• 速率限制：处理 API 速率限制超出（429 状态）。
• 网络问题：处理连接错误和超时。
• 意外错误：捕获并报告任何意外异常。

📄 API 文档

此服务器基于 AtData SafeToSend API 构建。有关底层 API 的更多详细信息，请参阅：

• AtData SafeToSend API 文档

🔧 开发

项目结构

atdata-mcp-server/
├── src/
│   └── server.py          # 主要的 MCP 服务器实现
├── pyproject.toml         # 项目配置和依赖项
├── uv.lock               # 锁定的依赖项
└── README.md             # 本文件

🤝 贡献

1. 分叉此仓库。
2. 创建一个功能分支。
3. 进行你的更改。
4. 如有必要，添加测试。
5. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

🛠️ 支持

如果你遇到以下相关问题：

• 此 MCP 服务器：在此仓库中创建一个问题。
• AtData API：联系 AtData 支持团队或查看他们的文档。
• FastMCP 框架：查看 FastMCP 文档