Truelist

truelist-mcp

用于 Truelist 邮件验证的 MCP（Model Context Protocol）服务。Claude、Cursor 和 VS Code Copilot 等 AI 助手可以通过它检查电子邮件地址是否可投递。

这是什么？

此软件包将 Truelist 的邮件验证 API 封装为 MCP 工具。配置完成后，AI 助手可以：

• 检查电子邮件地址是否有效且可投递
• 一次验证一批电子邮件
• 查看 Truelist 账户信息和套餐

免费开始 — 100 次验证 + 10 个增强验证额度，无需信用卡。 获取 API 密钥 → 免费套餐也可使用。

安装

npm install -g truelist-mcp

也可以直接使用 npx 运行：

npx truelist-mcp

配置

你需要一个 Truelist API 密钥。前往 truelist.io 获取。

Claude Desktop

添加到你的 claude_desktop_config.json：

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

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

Claude Code

添加到你的 .claude/settings.json，或运行：

claude mcp add truelist -- npx truelist-mcp

然后设置环境变量：

export TRUELIST_API_KEY=your-api-key

Cursor

添加到 Cursor MCP 设置（项目中的 .cursor/mcp.json 或全局设置）：

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

VS Code（GitHub Copilot）

添加到 VS Code 设置（项目中的 .vscode/mcp.json）：

{
  "servers": {
    "truelist": {
      "command": "npx",
      "args": ["truelist-mcp"],
      "env": {
        "TRUELIST_API_KEY": "your-api-key"
      }
    }
  }
}

工具

validate_email

检查单个电子邮件地址是否可投递。

输入：

{
  "email": "[email protected]"
}

输出：

{
  "email": "[email protected]",
  "state": "ok",
  "sub_state": "email_ok",
  "suggestion": null,
  "domain": "example.com",
  "canonical": "[email protected]",
  "mx_record": "mx.example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "verified_at": "2026-02-21T12:00:00Z",
  "is_valid": true,
  "is_deliverable": true
}

状态：

状态	含义
ok	邮件可投递
email_invalid	邮件不可投递
risky	邮件可能可投递，但存在风险因素
accept_all	域名接受所有地址；可投递性无法确定
unknown	无法确定可投递性

子状态：

子状态	含义
email_ok	未发现问题
accept_all	域名接受所有地址
is_disposable	临时或一次性邮箱
is_role	基于角色的地址（info@、support@ 等）
failed_mx_check	域名没有邮件服务器
failed_smtp_check	SMTP 验证失败
failed_spam_trap	已知的垃圾邮件陷阱地址
failed_no_mailbox	邮箱不存在
failed_greylisted	服务器暂时拒绝
failed_syntax_check	电子邮件语法无效
unknown	无法确定子状态

validate_emails

一次批量验证多个电子邮件地址（最多 50 个）。

输入：

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

输出：

[
  {
    "email": "[email protected]",
    "state": "ok",
    "sub_state": "email_ok",
    "is_valid": true
  },
  {
    "email": "[email protected]",
    "state": "email_invalid",
    "sub_state": "failed_mx_check",
    "is_valid": false
  },
  {
    "email": "[email protected]",
    "state": "ok",
    "sub_state": "email_ok",
    "is_valid": true
  }
]

check_account

查看你的 Truelist 账户信息，包括姓名、电子邮件、套餐和管理员状态。

输入： 无

输出：

{
  "email": "[email protected]",
  "name": "Your Name",
  "uuid": "a3828d19-...",
  "timeZone": "America/New_York",
  "isAdminRole": true,
  "paymentPlan": "pro"
}

环境变量

变量	必填	说明
TRUELIST_API_KEY	是	你的 Truelist API 密钥，可从 truelist.io 获取

故障排查

“TRUELIST_API_KEY environment variable is required”

此服务需要 TRUELIST_API_KEY 环境变量。请确保已在 MCP 配置的 env 块中设置，或在 Shell 中导出该变量。

Claude/Cursor 中未显示工具

1. 修改 MCP 配置后，重启 AI 助手
2. 设置 TRUELIST_API_KEY 后，检查 npx truelist-mcp 是否能正常运行
3. 确认配置文件路径与你的平台相符

身份验证错误

请在 truelist.io 确认你的 API 密钥正确且有效。

速率限制

Truelist 会对 API 实施速率限制。如果触发速率限制，SDK 会自动采用指数退避策略重试。批量验证时，邮件会并发验证，因此大型批次可能触发速率限制。

入门

注册一个免费的 Truelist 账户以获取 API 密钥。免费套餐包含 100 次验证和 10 个增强额度，无需信用卡。

许可证

MIT