MailVeri MCP v1

Official Model Context Protocol (MCP) server for MailVeri. Connect your AI assistants (Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Antigravity, OpenCode, Pi, Oh My Pi, VS Code Cline) directly to MailVeri's email deliverability and bulk verification engine.

Package: mailveri-mcp

Protocol: MCP Specification

GitHub: github.com/mailveri/mailveri-mcp

Dashboard: app.mailveri.com/mcp/

1. Overview

The Model Context Protocol (MCP) is an open standard that lets LLMs and AI Agents securely invoke external tools and query live data. The MailVeri MCP Server bridges LLMs directly with MailVeri's infrastructure without requiring manual API calls.

⚡ Real-Time Email Validation

Inspect MX records, SMTP handshakes, mailbox availability, catch-all domains, and disposable providers in milliseconds.

📦 Asynchronous Bulk Verification

Submit lists of emails from within chat sessions, monitor batch completion percentages, and retrieve signed result download URLs.

💰 Instant Balance & Quota Check

Agents can check remaining verification credits dynamically before running large outreach pipelines or processing contact files.

🚀 Zero-Install Execution

Instantly launchable via uvx directly from GitHub, ensuring you always execute the latest tools with zero local dependency clutter.

2. Prerequisites & Authentication

To use the MailVeri MCP server, you only need an active MailVeri API key and uv installed on your workstation.

MailVeri API Key: Retrieve or create your key in the MailVeri Console at app.mailveri.com/api-keys/ or visit app.mailveri.com/mcp/ for interactive configuration.

Install uv (Recommended Package Runner)

uv enables instantaneous tool execution without creating global Python environments:

Install uv (macOS / Linux / Windows)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. One-Click AI Setup Prompt

Paste this prompt directly into your AI assistant (e.g. Claude Desktop, Claude Code, Codex, Cursor, OpenCode, Pi, Oh My Pi, Antigravity) to let it automatically set up MailVeri MCP for you.

Prompt for AI Assistant

Please configure the MailVeri MCP (Model Context Protocol) email verification tool for me.

Configuration JSON:
{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Once configured, verify single emails using mailveri_verify_email or check balance using mailveri_get_balance.

4. Client Configurations

Configure MailVeri MCP across your favorite AI assistants and IDEs.

CLIENT Claude Desktop

macOS & Windows

Add the server definition to your Claude Desktop configuration file:

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

claude_desktop_config.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Claude Code

CLI Agent

Add MailVeri MCP to Anthropic's Claude Code CLI via the command line or by directly editing your configuration files:

Project-scoped (shared via repo): .mcp.json (at project root)
User-scoped (global for all projects): ~/.claude.json

CLI Command

claude mcp add --scope project --env MAILVERI_API_KEY=YOUR_MAILVERI_API_KEY mailveri -- uvx --from git+https://github.com/mailveri/mailveri-mcp mailveri-mcp

Or configure directly in .mcp.json (or ~/.claude.json):

.mcp.json / ~/.claude.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Codex

CLI & Agent

Configure MailVeri MCP in your Codex assistant or agent configuration file. The official Codex CLI uses TOML format:

Global CLI config: ~/.codex/config.toml
Project CLI config: .codex/config.toml
Alternative / GUI integrations: ~/.codex/config.json

~/.codex/config.toml

[mcp_servers.mailveri]
command = "uvx"
args = ["--from", "git+https://github.com/mailveri/mailveri-mcp", "mailveri-mcp"]

[mcp_servers.mailveri.env]
MAILVERI_API_KEY = "YOUR_MAILVERI_API_KEY"

If using JSON configuration:

~/.codex/config.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Cursor IDE

Project & Global

Add MailVeri MCP via GUI under Cursor Settings > Features > MCP, or add directly to your configuration files:

Project-level: .cursor/mcp.json
Global user-level: ~/.cursor/mcp.json

.cursor/mcp.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Windsurf (Codeium)

mcp_config.json

Configure via GUI in Windsurf Settings > Cascade > MCP Servers, or directly edit the configuration file:

Configuration path: ~/.codeium/windsurf/mcp_config.json

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Google Antigravity

mcp_config.json / settings

Configure under global user settings or per-workspace settings:

Global config: ~/.gemini/antigravity/mcp_config.json
Workspace config: .gemini/antigravity/mcp_config.json

mcp_config.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT OpenCode

CLI Terminal

OpenCode discovers configuration files in the following precedence order:

Global (Home): ~/.opencode.json
Global (XDG): ~/.config/opencode/.opencode.json
Project directory: ./.opencode.json

.opencode.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Pi

CLI & Agent

Configure MailVeri MCP in your Pi AI assistant settings:

Global Agent config: ~/.pi/agent/mcp.json or ~/.pi/config.json
Project config: .pi/mcp.json

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT Oh My Pi

CLI Terminal

Configure in Oh My Pi MCP registry:

Global config: ~/.omp/mcp.json
Project config: ./.omp/mcp.json

~/.omp/mcp.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

CLIENT VS Code / Cline / Roo-Code

Extension Config

Configure via the Cline extension MCP settings tab, or edit cline_mcp_settings.json directly:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

cline_mcp_settings.json

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_MAILVERI_API_KEY"
      },
      "disabled": false,
      "autoApprove": [
        "mailveri_verify_email",
        "mailveri_get_balance"
      ]
    }
  }
}

5. MCP Tools Reference

Detailed parameter definitions, response schemas, and deliverability status indicators for all 6 tools exposed by the MailVeri MCP Server.

TOOL mailveri_verify_email

1 Credit

Verifies the existence and deliverability of a single target email address. Checks MX existence, connects to the destination mail exchanger via SMTP handshake, evaluates catch-all configurations, disposable email providers, and role accounts.

Input Arguments

Field	Type	Required	Description
`email`	string	Required	Target email address (e.g. `[email protected]`).

Output JSON Schema

Tool Result Response

{
  "status": "VALID",
  "email": "[email protected]",
  "balance": 999
}

Deliverability Status Enum

Status	Meaning	Deliverability Advice
VALID	Mailbox verified successfully. SMTP 250 OK accepted.	Safe to send. Lowest bounce probability.
INVALID	Recipient address does not exist, syntax is invalid, or domain has no MX.	Do not send. Hard bounce guaranteed.
DISPOSABLE	Temporary, burnable email provider (e.g. GuerrillaMail, 10MinuteMail).	Block or filter out to preserve sender reputation.
ROLE_ACCOUNT	Functional company address (e.g. `support@`, `info@`, `sales@`).	Higher complaint risk; proceed with care.
CATCH_ALL	Domain server accepts all incoming emails regardless of username.	Proceed cautiously; deliverability cannot be guaranteed.
FULL_INBOX	Recipient mailbox storage quota is exceeded.	Do not send. Soft bounce expected.
UNKNOWN	Remote mail server greylisted, timed out, or connection refused.	Temporary issue. Retry verification later.

TOOL mailveri_get_balance

Free

Checks the current verification credits remaining in your MailVeri account. Takes no arguments.

Output JSON Schema

Tool Result Response

{
  "status": "success",
  "balance": 4820
}

TOOL mailveri_verify_batch

1 Credit / Email

Queues a list of emails (minimum 2 unique email addresses) for asynchronous, distributed bulk verification. Returns an identifier id to monitor job progress.

Input Arguments

Field	Type	Required	Description
`emails`	array<string>	Required	Array of email strings (at least 2 unique items).
`filename`	string	Optional	Optional label filename for the batch archive (default: `batch.csv`).

Output JSON Schema

Tool Result Response

{
  "id": "sample_batch_id_9x8y7z",
  "status": "QUEUED",
  "count": 250,
  "filename": "leads_2026_q1.csv"
}

TOOL mailveri_get_batch_status

Free

Polls progress percentage, status state, and download links for an active or completed bulk verification job.

Input Arguments

Field	Type	Required	Description
`job_id`	string	Required	The batch identifier returned from `mailveri_verify_batch`.

Output JSON Schema

Tool Result Response

{
  "id": "sample_batch_id_9x8y7z",
  "status": "DONE",
  "percent": 100,
  "download_link": "https://api.mailveri.com/v1/download-result/?id=sample_batch_id_9x8y7z"
}

TOOL mailveri_download_batch_result

Free

Returns the direct authenticated download URL for the resulting ZIP archive of a completed batch job.

Input Arguments

Field	Type	Required	Description
`job_id`	string	Required	The completed batch ID.

Output JSON Schema

Tool Result Response

{
  "status": "DONE",
  "download_link": "https://api.mailveri.com/v1/download-result/?id=bX9K3LwZqP2YtR8vN4mQ"
}

TOOL mailveri_delete_batch

Free

Cancels an ongoing verification job or deletes a completed batch and its associated result files.

Input Arguments

Field	Type	Required	Description
`job_id`	string	Required	Batch ID to cancel or delete.

Output JSON Schema

Tool Result Response

{
  "status": "deleted",
  "id": "bX9K3LwZqP2YtR8vN4mQ"
}

6. Transports & Execution Modes

MailVeri MCP Server is built with FastMCP and supports both standard I/O (stdio) and Server-Sent Events (sse).

Transport	Flag	Best Used For
`stdio` (Default)	`--transport stdio`	Desktop and CLI clients like Claude Desktop, Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity where the host process manages the server lifecycle.
`sse`	`--transport sse --port 8000`	Remote deployments, Docker containers, multi-client team servers running over HTTP/SSE.

Environment Variables

Variable	Default	Description
`MAILVERI_API_KEY`	None	Required. Your MailVeri API key / Auth-Token.

7. Troubleshooting & FAQ

Q: `uvx: command not found` error

Make sure uv is installed and available in your shell's PATH. If Claude Desktop doesn't find uvx, provide the full absolute path in your config (e.g. /usr/local/bin/uvx or /Users/<user>/.cargo/bin/uvx).

Q: Rate limit warnings on single verification

Single email verification (mailveri_verify_email) is limited to 1 request per second. For lists containing 2 or more emails, instruct your AI agent to use mailveri_verify_batch for optimal speed and throughput.

Q: Tool call returns `{"error": 1, "message": "Invalid API key"}`

Verify that your MAILVERI_API_KEY environment variable is correctly set in your client's config file and that your key is active in your MailVeri Dashboard.

1. Overview

⚡ Real-Time Email Validation

📦 Asynchronous Bulk Verification

💰 Instant Balance & Quota Check

🚀 Zero-Install Execution

2. Prerequisites & Authentication

Install uv (Recommended Package Runner)

3. One-Click AI Setup Prompt

4. Client Configurations

5. MCP Tools Reference

Input Arguments

Output JSON Schema

Deliverability Status Enum

Output JSON Schema

Input Arguments

Output JSON Schema

Input Arguments

Output JSON Schema

Input Arguments

Output JSON Schema

Input Arguments

Output JSON Schema

6. Transports & Execution Modes

Environment Variables

7. Troubleshooting & FAQ

Q: uvx: command not found error

Q: Rate limit warnings on single verification

Q: Tool call returns {"error": 1, "message": "Invalid API key"}

Q: `uvx: command not found` error

Q: Tool call returns `{"error": 1, "message": "Invalid API key"}`