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 社区用心打造 ❤️