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 文檔