Zapmail MCP

🚀 Zapmail MCP 服務器

Zapmail MCP 服務器是一個針對 Zapmail API 的模型上下文協議（MCP）服務器，它提供了自然語言方式來進行域名管理、郵箱操作和導出等功能。該軟件包使像 Claude 這樣的 AI 助手能夠通過自然語言命令與 Zapmail 進行交互。

✨ 主要特性

• 全面覆蓋 Zapmail API（46 種以上工具）
• 支持自然語言命令處理
• 可根據 API 文檔動態生成工具
• 支持導出到 Reachinbox、Instantly、Smartlead、Reply.io 以及 CSV 格式
• 具備帶 TTL 的緩存系統
• 支持速率限制和錯誤處理
• 支持多工作區
• 可與 Claude Desktop 和 Cursor 進行 MCP 集成

📦 安裝指南

選項 1：使用 npx（推薦）

無需安裝，直接使用 npx 運行：

npx zapmail-mcp

選項 2：全局安裝

全局安裝以便持久使用：

npm install -g zapmail-mcp

🚀 快速開始

步驟 1：獲取 Zapmail API 密鑰

• 在 Zapmail 上註冊賬號。
• 導航到 API 設置頁面。
• 生成一個新的 API 密鑰。

步驟 2：配置 MCP 客戶端

• 選擇你喜歡的 MCP 客戶端（Claude Desktop 或 Cursor）。
• 將上述配置 JSON 添加到你的 MCP 設置中。
• 將 your-zapmail-api-key 替換為你實際的 API 密鑰。

步驟 3：測試連接

• 打開你的 MCP 客戶端。
• 嘗試使用自然語言命令，例如：
  • “列出我所有的 Zapmail 工作區”
  • “顯示我的域名”
  • “檢查 example.com 是否可購買”

💻 使用示例

域名操作

檢查域名可用性

在 Claude Desktop 或 Cursor 中輸入：

"檢查 example.com 是否可購買 1 年"

購買域名

在 Claude Desktop 或 Cursor 中輸入：

"如果可能，使用錢包購買 example.com 和 test.com 1 年"

郵箱管理

在空域名上創建郵箱

在 Claude Desktop 或 Cursor 中輸入：

"在沒有郵箱的域名上創建 5 個郵箱"

批量更新郵箱

在 Claude Desktop 或 Cursor 中輸入：

"用新的名稱和詳細信息更新所有郵箱"

導出操作

導出到 Reachinbox

在 Claude Desktop 或 Cursor 中輸入：

"連接我的 Reachinbox 賬戶並導出所有郵箱"

獲取導出指南

在 Claude Desktop 或 Cursor 中輸入：

"幫我將 100 個郵箱導出到 Reachinbox"

複雜工作流程

多步驟操作

在 Claude Desktop 或 Cursor 中輸入：

"購買 example.com 和 test.com，在每個域名上創建 5 個郵箱，並導出到 reachinbox"

工作區管理

在 Claude Desktop 或 Cursor 中輸入：

"顯示我所有的工作區，並切換到域名最多的工作區"

系統監控

健康檢查

在 Claude Desktop 或 Cursor 中輸入：

"檢查我的 Zapmail 連接健康狀況"

獲取指標

在 Claude Desktop 或 Cursor 中輸入：

"顯示我的 Zapmail 操作性能指標"

📚 詳細文檔

可用工具

核心管理工具

• set_context - 設置工作區和提供商上下文
• wallet_balance - 獲取錢包餘額
• list_workspaces - 列出所有工作區
• list_domains - 列出工作區中的域名
• check_domain_availability - 檢查域名可用性
• purchase_domains - 購買域名（優先使用錢包）
• create_mailboxes_for_zero_domains - 在空域名上創建郵箱
• add_third_party_account - 添加第三方導出賬戶
• call_endpoint - 調用任何 Zapmail 端點
• generate_usernames - 生成郵箱用戶名
• generate_name_pairs - 生成名稱對
• generate_domains - 生成由 AI 驅動的域名建議
• check_domain_availability_batch - 批量檢查域名可用性
• plan_and_execute - 自然語言規劃與執行
• get_server_info - 獲取服務器信息

系統管理工具

• get_metrics - 獲取系統指標和性能數據
• clear_cache - 清除系統緩存
• health_check - 系統健康檢查

高級郵箱工具

• bulk_update_mailboxes - 批量更新郵箱
• search_mailboxes - 使用高級過濾器搜索郵箱

導出系統工具

• get_export_info - 獲取導出系統信息
• get_export_scenario - 獲取導出場景說明
• validate_export_request - 驗證導出請求參數
• export_guidance - 獲取導出指南和最佳實踐

API 文檔工具

• get_api_info - 獲取全面的 API 端點信息
• search_api_endpoints - 按關鍵字搜索 API 端點
• get_api_scenarios - 獲取常見的 API 使用場景
• get_api_best_practices - 獲取 API 最佳實踐和建議
• generate_api_examples - 生成 API 使用示例

動態 API 工具

所有文檔化的 API 端點均可自動生成工具

自然語言命令

連接到 MCP 客戶端後，你可以使用自然語言控制 Zapmail：

工作區和域名管理

• “列出我所有的工作區”
• “顯示當前工作區中包含‘lead’的域名”
• “檢查 leadconnectlab.com 是否可購買 2 年”
• “如果可能，使用錢包購買 leadconnectlab.com 和 outreachprohub.com 1 年”

郵箱管理

• “在沒有郵箱的每個域名上創建 3 個郵箱”
• “為我設置 100 個郵箱並連接到 Instantly.ai”
• “用新名稱更新所有郵箱”

導出操作

• “將所有郵箱導出到 reachinbox”
• “將郵箱導出到 instantly”
• “將郵箱導出為 CSV 格式”
• “導出特定郵箱”
• “從 leadconnectio.com 域名導出郵箱”

第三方集成

• “連接 reachinbox 賬戶”
• “添加 instantly 憑證”
• “鏈接 smartlead 賬戶”
• “設置 reply.io 集成”

配置

環境變量

屬性	詳情
ZAPMAIL_API_KEY	你的 Zapmail API 密鑰
ZAPMAIL_WORKSPACE_KEY	默認工作區 ID
ZAPMAIL_SERVICE_PROVIDER	電子郵件提供商（GOOGLE/MICROSOFT）
ZAPMAIL_LOG_LEVEL	日誌記錄級別（DEBUG/INFO/WARN/ERROR）
ZAPMAIL_MAX_RETRIES	最大重試次數
ZAPMAIL_TIMEOUT_MS	請求超時時間（毫秒）
ZAPMAIL_ENABLE_CACHE	是否啟用響應緩存
ZAPMAIL_ENABLE_METRICS	是否啟用性能指標
ZAPMAIL_RATE_LIMIT_DELAY	速率限制延遲（毫秒）
OPENAI_API_KEY	用於增強自然語言處理的 OpenAI API 密鑰

命令行選項

版本信息

npx zapmail-mcp --version
# 或者
npx zapmail-mcp -v

幫助信息

npx zapmail-mcp --help
# 或者
npx zapmail-mcp -h

🔧 技術細節

MCP 配置

對於 Claude Desktop

創建或更新 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

使用 npx（推薦）：

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

使用全局安裝：

{
  "mcpServers": {
    "zapmail": {
      "command": "zapmail-mcp",
      "args": [],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

對於 Cursor

添加到你的 Cursor MCP 設置中： 使用 npx（推薦）：

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

使用全局安裝：

{
  "mcpServers": {
    "zapmail": {
      "command": "zapmail-mcp",
      "args": [],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

故障排除

MCP 連接問題

1. 未找到 MCP 服務器

問題：“未找到 zapmail-mcp 命令” 或 “未找到 npx zapmail-mcp” 解決方案： 對於 npx 使用：

# 直接測試 npx
npx zapmail-mcp --version

# 如果 npx 失敗，嘗試使用顯式的包版本
npx zapmail-mcp@latest --version

# 獲取幫助信息
npx zapmail-mcp --help

對於全局安裝：

# 全局安裝包
npm install -g zapmail-mcp

# 驗證安裝
zapmail-mcp --version

2. MCP 客戶端未檢測到服務器

問題：Zapmail 工具未在 Claude Desktop/Cursor 中顯示 解決方案：

• 重啟你的 MCP 客戶端（Claude Desktop/Cursor）
• 檢查你的 MCP 配置文件語法
• 驗證配置中的命令路徑

3. API 密鑰問題

問題：“未配置 ZAPMAIL_API_KEY” 解決方案：

• 在 MCP 配置中設置環境變量：

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

• 或者全局設置：

export ZAPMAIL_API_KEY="your-api-key"

4. 工作區上下文問題

問題：從錯誤的工作區獲取數據 解決方案：在 MCP 配置中設置工作區：

{
  "env": {
    "ZAPMAIL_WORKSPACE_KEY": "your-workspace-id"
  }
}

性能問題

1. 響應時間慢

問題：MCP 操作耗時過長 解決方案：

• 啟用緩存：ZAPMAIL_ENABLE_CACHE="true"
• 增加速率限制延遲：ZAPMAIL_RATE_LIMIT_DELAY="2000"
• 檢查你的互聯網連接

2. 速率限制

問題：出現 “請求過多” 錯誤 解決方案：在 MCP 配置中增加速率限制延遲：

{
  "env": {
    "ZAPMAIL_RATE_LIMIT_DELAY": "2000"
  }
}

調試模式

啟用調試日誌以進行詳細的故障排除：

{
  "env": {
    "ZAPMAIL_LOG_LEVEL": "DEBUG"
  }
}

健康檢查

測試你的 MCP 連接： 在 Claude Desktop 或 Cursor 中輸入：

"檢查我的 Zapmail 連接健康狀況"

常見 MCP 配置錯誤

1. 無效的 JSON 語法

問題：MCP 客戶端無法加載配置 解決方案：使用 JSON 驗證器驗證你的 JSON 配置

2. 錯誤的命令路徑

問題：MCP 客戶端中出現 “未找到命令” 解決方案：使用完整路徑或確保 zapmail-mcp 在你的 PATH 中

3. 環境變量未加載

問題：API 密鑰未傳遞到 MCP 服務器 解決方案：在 MCP 配置中使用 env 部分，而不是全局環境變量

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

包信息

• 包名稱：zapmail-mcp
• 版本：0.0.2
• NPM：zapmail-mcp
• GitHub：dsouzaalan/zapmail-mcp

支持

如需支持和諮詢：

• 查看上述故障排除部分
• 查看 MCP 配置示例
• 通過健康檢查測試你的連接
• 啟用調試日誌以獲取詳細的錯誤信息
• 訪問 GitHub 倉庫 進行問題討論

貢獻

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 如有必要添加測試
5. 提交拉取請求

---

為 Zapmail 社區用心打造 ❤️