byteplant-mcp

Byteplant MCP 服务

通过任意 MCP 客户端验证电子邮件地址、电话号码和邮政地址，
精度无与伦比，覆盖全球 240 多个国家和地区。

安装 · 工具 · 凭据 · 用法 · 兼容性 · 资源

---

这是一个 MCP 服务，可将 Claude、Cursor 和 VS Code 等 AI 助手连接到 Byteplant 验证 API。请助手检查电子邮件地址、电话号码或邮政地址，它就会调用相应的 Byteplant 工具并读回结果。

此服务在你的计算机上本地运行，并通过 stdio 与 MCP 客户端通信。

安装

运行此服务最简单的方式是使用 uv。uvx 会自动下载此软件包和合适的 Python 版本，因此无需安装其他内容。

使用以下任一配置将此服务添加到 MCP 客户端，并将占位符替换为你的 API 密钥。你只需提供所用服务对应的密钥。

Claude Desktop

1. 在 Claude Desktop 中，前往 Settings → Developer → Edit Config。这会打开 claude_desktop_config.json：

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

2. 添加 Byteplant 服务：

   {
     "mcpServers": {
       "byteplant": {
         "command": "uvx",
         "args": ["byteplant-mcp@latest"],
         "env": {
           "EV_TOKEN": "<EMAIL VALIDATOR API KEY>",
           "PV_TOKEN": "<PHONE VALIDATOR API KEY>",
           "AV_TOKEN": "<ADDRESS VALIDATOR API KEY>"
         }
       }
     }
   }
   

3. 重启 Claude Desktop。

Claude Code

claude mcp add \
  --env EV_TOKEN=<EMAIL VALIDATOR API KEY> \
  --env PV_TOKEN=<PHONE VALIDATOR API KEY> \
  --env AV_TOKEN=<ADDRESS VALIDATOR API KEY> \
  --transport stdio byteplant -- uvx byteplant-mcp@latest

Cursor

将与 Claude Desktop 相同的 mcpServers 条目添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。

VS Code

将此服务添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "byteplant": {
      "type": "stdio",
      "command": "uvx",
      "args": ["byteplant-mcp@latest"],
      "env": {
        "EV_TOKEN": "<EMAIL VALIDATOR API KEY>",
        "PV_TOKEN": "<PHONE VALIDATOR API KEY>",
        "AV_TOKEN": "<ADDRESS VALIDATOR API KEY>"
      }
    }
  }
}

使用 pip 代替 uv

pip install byteplant-mcp

这会安装 byteplant-mcp 命令。请使用其完整路径作为命令，因为桌面应用通常无法读取 shell 的 PATH（在 macOS/Linux 上使用 which byteplant-mcp 查找路径，在 Windows 上使用 where byteplant-mcp）：

"command": "/full/path/to/byteplant-mcp"

或者，使用安装此软件包的 Python 环境运行模块：

"command": "/path/to/python",
"args": ["-m", "byteplant_mcp"]

工具

工具	功能
validate_email	检查电子邮件地址是否可送达，并检测免费电子邮件服务提供商
validate_phone	验证电话号码，并返回其线路类型、运营商代码、位置和格式
validate_address	验证并规范化邮政地址，可选择进行地理编码

凭据

每个工具都使用各自的 API 密钥，并通过环境变量传递给服务。注册所需的服务即可获取密钥：

环境变量	使用该变量的工具	获取 API 密钥
EV_TOKEN	validate_email	电子邮件验证器
PV_TOKEN	validate_phone	电话验证器
AV_TOKEN	validate_address	地址验证器

你可以在 Byteplant 账户中管理密钥。如果缺少密钥，相应工具会告知助手需要设置哪个变量，而不会调用 API。

用法

只需用日常语言向助手提问，例如：

• “[email protected] 是有效的电子邮件地址吗？”
• “检查 +49 9874 322466 是手机号码还是固定电话。”
• “验证此地址，并提供标准化版本：Heilsbronner Str. 4, 91564 Neuendettelsau, Germany。”

助手会填写以下工具参数。每个工具还都有一个 timeout 参数，用于设置 API 响应所需的最长时间：5–300 秒，默认值为 10。

validate_email - API 文档

参数	必填	说明
email	✅	要验证的电子邮件地址

输出

字段	说明
status	数字结果代码，例如，地址有效时为 200。请参阅完整结果代码列表。
category	由服务添加：根据 status 确定为 VALID、SUSPECT、INVALID 或 INDETERMINATE（未列出的代码为 UNKNOWN）
status_description	由服务添加：status 代码的含义
info	简短状态说明
details	完整状态说明
freemail	如果该地址属于免费电子邮件服务提供商（Gmail、Yahoo、Outlook/Hotmail/Live、AOL 等），则为 true

validate_phone - API 文档

参数	必填	说明
phone	✅	要验证的电话号码，采用国内格式，或采用以 + 开头的国际格式
code		两字母 ISO 3166-1 国家/地区代码。电话号码为国际格式时可选。
locale		用于地理编码结果的 IETF 语言标签。默认为 en-US。
mode		extensive（默认）执行完整验证。express 仅执行静态检查，速度更快。

输出

字段	说明
status	VALID_CONFIRMED、VALID_UNCONFIRMED、INVALID、DELAYED、RATE_LIMIT_EXCEEDED 或 API_KEY_INVALID_OR_DEPLETED
linetype	FIXED_LINE、MOBILE、VOIP、TOLL_FREE、PREMIUM_RATE、SHARED_COST、PERSONAL_NUMBER、PAGER、UAN 或 VOICEMAIL
location	地理位置（城市、县、州）
countrycode	两字母 ISO 3166-1 国家/地区代码
formatnational	国内格式的电话号码
formatinternational	国际格式的电话号码
mcc	移动国家代码，用于标识移动网络运营商（运营商）
mnc	移动网络代码，用于标识移动网络运营商（运营商）

validate_address - API 文档

参数	必填	说明
code	✅	两字母 ISO 3166-1 国家/地区代码。国际地址请使用 XX。
street_adr	✅	街道、门牌号和建筑物。可包含单元或公寓信息，也可填写完整地址。
street_num		如果门牌号或建筑物编号未包含在 street_adr 中，请在此填写
additional_info		建筑物、单元、公寓或楼层
city		城市或地区
postal_code		ZIP 或邮政编码
state		州或省
geocoding		是否返回地址的坐标。默认关闭。
locale		适用于具有多种邮政语言的国家/地区的输出语言。仅在翻译地址时使用；验证地址时留空。
charset		utf-8（默认）或 us-ascii

输出

字段	描述
status	VALID：地址正确且可投递。SUSPECT：地址需要修正才能投递，并提供了建议的修正内容。INVALID：地址不可投递，无法自动修正。其他值：DELAYED、NO_COUNTRY、RATE_LIMIT_EXCEEDED、API_KEY_INVALID_OR_DEPLETED、RESTRICTED、INTERNAL_ERROR
formattedaddress	标准化格式的完整地址
supplement	地址补充信息（建筑物、单元、套房、公寓）
street	标准化格式的街道
streetnumber	标准化格式的门牌号
postalcode	标准化格式的 ZIP 或邮政编码
city	标准化格式的城市
district	标准化格式的区
county	标准化格式的县
state	标准化格式的州或省
country	两字母 ISO 3166-1 国家/地区代码
type	地址类型：S 表示街道地址，P 表示邮政信箱、取件点或其他配送服务
rdi	住宅投递标识：商业地址或住宅地址
diagnostics	关于地址输入错误的提示。请参阅诊断提示完整列表。
corrections	关于地址输入中哪些部分已修正的提示。请参阅修正提示完整列表。
latitude、longitude	坐标。仅在地址有效且启用了 geocoding 时返回。

兼容性

要求	版本
Python	3.10 或更高版本（由 uvx 自动安装）
MCP 客户端	任何可运行本地 stdio 服务的客户端，例如 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 或 OpenAI Codex

ChatGPT 和 Claude 的网页版或移动版仅连接远程（托管）MCP 服务，因此目前无法使用此服务。

资源

• Model Context Protocol 文档
• Email Validator API 文档
• Phone Validator API 文档
• Address Validator API 文档
• Byteplant 网站
• 联系方式：[email protected]

许可证

MIT