Skip to main content
Glama
contact-verification-mcp

contact-verification-mcp

by D2Emerge

contact-verification-mcp

一个包装了 Melissa 的 Global Address、Global Email 和 Global Phone 验证 API 的 MCP 服务器。它是为配合 SD Times / Melissa 开发者文章《为验证 API 构建一个 MCP 服务器》而构建的。

这是什么

智能体可以在对联系数据采取行动之前调用三个工具来检查其真实性,外加一个批量工具和每次会话的调用预算,防止智能体循环调用导致账单失控:

  • verify_postal_address

  • verify_email

  • verify_phone

  • verify_batch

关于工具描述背后的设计选择、三态(已确认 / 部分确认 / 未确认)结果,以及为什么刻意不暴露电话线路类型,请参阅 src/melissaClient.ts。

Related MCP server: Mailveri MCP Server

设置

npm install
cp .env.example .env
# edit .env and set MELISSA_LICENSE_KEY to your own key
npm run build
npm start

该服务器通过 stdio 使用 MCP 协议进行通信,因此它应由 MCP 客户端(Claude Code、Claude Desktop 或任何其他兼容 MCP 的主机)启动,而不是为交互式使用而独立运行。

测试

npm test          # runs entirely against recorded fixtures, no network calls, no key required
npm run typecheck  # type-checks src/ and tests/ together

tests/fixtures/ 中的测试带有一个 _source 字段:REAL 表示从 Melissa 发布的 OpenAPI 示例中逐字复制(github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications);SYNTHETIC 表示是因为 Melissa 的公开规范中没有该形状的真实示例(主要是失败用例)而构造出来的,用于测试覆盖。不要将合成夹具的具体结果码当作已经真实账户验证过的。

运行真实测试

MELISSA_LICENSE_KEY=your-real-key npm run test:live

这会真实调用 Melissa 的 API 并消耗 API 额度。它永远不会作为 npm test 或 CI 的一部分运行。不要把真实密钥放在任何已提交的文件中;只能在运行时将其设置为环境变量。

结果代码来源

本代码库中引用的每个 Melissa 结果代码(AV24、ES01、ES07、ES08、ES21、PS01、PS20、PS22)都已通过 grep 搜索 Melissa 自己发布的 OpenAPI 规范示例确认,而不是猜测或旧文章草稿相关。具体如下:

  • AV24 是 Melissa 的 Global Address 规范示例中出现的唯一 AV 前缀代码。没有针对独立的“已确认到子场所”层级的已确认代码,因此该客户端不宣称这一层级。

  • Global Email 的规范示例只显示 ES 前缀代码。该规范中从不出现任何 EE 前缀代码。

  • Global Phone 的线路类型检测(mobile/landline/VoIP)在文档中仅限 Premium 模式且仅限美国/加拿大,因此此处不作为通用能力提供。

如果你的账户真实响应包含上述以外的代码,那说明该客户端需要更新,而不是新代码以错。

尚未完成的工作

  • 用于多实例部署的 Redis 缓存(目前仅支持进程内 LRU,见 src/cache.ts)。

  • 对启用了 Premium 模式的账户提供线路类型检测,置于功能开关之后。

  • 在 Melissa 自身规范中的 US/UK/DE 示例之外,对 Global Address 进行更广泛的国家/地区覆盖测试。

Available Tools

4 tools
verify_batchVerify many addresses, emails, or phone numbers in one callA

Use this instead of calling verify_postal_address, verify_email, or verify_phone in a loop. Checks a local cache before calling Melissa, and is subject to the same per-session call budget as the single-record tools. Provide exactly one of addresses, emails, or phoneNumbers.

Inputs: emails, addresses, phoneNumbers.

verify_emailVerify an email address against mailbox and domain reference dataA

Checks whether an email address is deliverable, not merely well-formed. Returns a deliverability confidence score (0-100) and result codes. Call this before sending anything time-sensitive or before treating an email address as a verified contact channel. Do NOT use this as an identity check; a deliverable mailbox does not confirm who controls it.

Inputs: email (required).

verify_phoneVerify a phone number against carrier reference dataA

Checks whether a phone number is valid and returns a standardized version. Does NOT report line type (mobile/landline/VoIP): Melissa exposes that only in Premium mode for US/CA numbers, which this tool does not assume is enabled. Do not use this tool's output to infer SMS deliverability.

Inputs: phoneNumber (required).

verify_postal_addressVerify a postal address against authoritative postal dataA

Checks whether a postal address exists and is deliverable, using maintained postal reference data. Returns a verification level, a corrected and standardized version of the address, and a persistent identifier for the physical location. Call this before any action that depends on an address being real: shipping, billing, account creation, or writing an address to a system of record. Do NOT use this to look up who lives at an address, and do not treat a verified address as evidence that a particular person is associated with it. This tool cannot confirm an address that is newly built or not yet in postal records; a 'not confirmed' result means unknown, not fabricated.

Inputs: country (required), addressLine (required), locality, postalCode, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct resource (address, email, phone) or a batch wrapper that explicitly replaces the single-record tools. The descriptions clearly differentiate purposes (e.g., email verification ≠ identity check).

    Naming Consistency5/5

    All tool names follow the consistent pattern 'verify_' + a clear noun (postal_address, email, phone, batch). The convention is uniform and predictable.

    Tool Count5/5

    Four tools cover the core verification operations (address, email, phone, plus a batch version). This is well-scoped and avoids unnecessary bloat or redundancy.

    Completeness5/5

    The tool surface covers the essential contact verification methods (postal, email, phone) and adds batch processing for efficiency. The descriptions explicitly disclaim unsupported features (e.g., phone line type, identity confirmation), making the scope clear with no obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to verify email addresses in real-time, checking syntax, DNS, MX records, and SMTP handshake, returning verdicts and deliverability scores without sending actual emails.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to verify email deliverability and check mailbox existence, manage bulk verification batches, and monitor verification credit balances directly from chat.
      6
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables agents to validate and normalize phone numbers, email addresses, and postal addresses with production-grade, country-specific rules, including formatting, typo detection, and checks for disposable domains or fictional numbers.
      3
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to verify single email addresses and bulk lists of up to 1,000 addresses in real time, checking RFC 5322 syntax, DNS MX records, disposable providers, role accounts, and typos, with an optional deep SMTP mailbox handshake. Bulk runs handle partial-quota situations gracefully.
      2
      MIT