Skip to main content
Glama
Sign In
deenesjakoruzh
contact-verification-mcp

contact-verification-mcp

by D2Emerge
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

contact-verification-mcp

An MCP server wrapping Melissa's Global Address, Global Email, and Global Phone verification APIs. Built to accompany the SD Times / Melissa developer article "Building an MCP Server for a Verification API."

What this is

Three tools an agent can call to check whether contact data is real before acting on it, plus a batch tool and a per-session call budget so an agent can't loop itself into a runaway bill:

  • verify_postal_address

  • verify_email

  • verify_phone

  • verify_batch

See src/melissaClient.ts for the design choices behind the tool descriptions, the three-state (confirmed / partially confirmed / not confirmed) results, and why phone line-type is deliberately not exposed.

Related MCP server: Mailveri MCP Server

Setup

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

The server speaks MCP over stdio, so it's meant to be launched by an MCP client (Claude Code, Claude Desktop, or any other MCP-compatible host), not run standalone for interactive use.

Testing

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

Fixtures in tests/fixtures/ are marked with a _source field: REAL means copied verbatim from Melissa's published OpenAPI examples (github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications); SYNTHETIC means constructed for test coverage because no real example of that shape exists in Melissa's public spec (failure cases, mainly). Don't treat a synthetic fixture's exact result codes as verified against a live account.

Running live tests

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

This makes real calls against Melissa's API and costs API credits. It is never run as part of npm test or CI. Do not put a real key in any committed file; set it as an environment variable at run time only.

Result code provenance

Every Melissa result code referenced in this codebase (AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22) was confirmed by grep-ing Melissa's own published OpenAPI spec examples, not guessed or carried over from an older article draft. Specifically:

  • AV24 is the only AV-prefixed code that appears anywhere in Melissa's Global Address spec examples. There is no confirmed code for a distinct "confirmed to subpremises" tier, so this client does not claim one.

  • Global Email's spec examples only ever show ES-prefixed codes. No EE-prefixed code appears anywhere in that spec.

  • Global Phone's line-type detection (mobile/landline/VoIP) is documented as Premium-mode-only and US/CA-only, so it is not surfaced as a general capability here.

If your account's real responses include codes not listed above, that's a sign this client needs updating, not that the new code is wrong.

What's not done yet

  • Redis-backed cache for multi-instance deployments (currently in-process LRU only, see src/cache.ts).

  • Line-type detection behind a feature flag for accounts with Premium mode enabled.

  • Broader country coverage testing for Global Address beyond the US/UK/DE examples in Melissa's own spec.

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…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    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.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Email Verifier MCP Server

      iguha0
      F
      license
      Not graded
      quality
      B
      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.
      -
    • Mailveri MCP Server

      Mailveri MCP Serverofficial

      mailveri
      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

    • contact-check

      arhancanli
      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

    • NoBounce Email Validation MCP

      notprathap
      A
      license
      A
      quality
      C
      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