MailVeri MCP Server 🚀

Official Model Context Protocol (MCP) server for MailVeri — Fast, accurate, and privacy-friendly email deliverability verification for AI agents and coding assistants.

📖 Interactive Documentation: For advanced client configurations, tool parameters, and error codes, visit our official MailVeri MCP Documentation.
🧠 Agent Skill (SKILL.md): Includes SKILL.md with pre-send deliverability routing rules (VALID, ROLE_ACCOUNT for SMBs, CATCH_ALL, zero-cost UNKNOWN) for Claude Code, Cursor, Hark, OpenClaw, and AgentMail (agentmail.to) pipelines.
📰 Step-by-step Tutorial: Read our comprehensive guide on How to Verify Emails Directly in Claude, Cursor & Windsurf.
⚡ Official Registries: Listed on Glama.ai and indexed in the Smithery Registry (mailveri/mailveri-mcp).

This server enables AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Antigravity, OpenCode, Pi, Oh My Pi, etc.) to verify email deliverability, check mailbox existence, check credit balances, and manage bulk verification batches directly from chat.

Features & Tools

Quick Start

1-Click Install via Smithery

Add to your MCP client in one command:

npx -y smithery mcp add mailveri/mailveri-mcp

1. Get Your MailVeri API Key

Sign up or log in to the MailVeri Dashboard and copy your API Key from Dashboard → API Keys: 👉 https://app.mailveri.com/api-keys/

2. Configuration for Claude Desktop

Add this configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\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"
      }
    }
  }
}

Note: Requires uv installed on your system (curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv).

3. Configuration for Claude Code

Run with Anthropic's Claude Code CLI:

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

Or add to ~/.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"
      }
    }
  }
}

4. Configuration for Codex

Add to your Codex config (~/.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"
      }
    }
  }
}

5. Configuration for Cursor

In Cursor, open Settings > Features > MCP Servers > Add New MCP Server:

• Name: mailveri
• Type: command
• Command: uvx --from git+https://github.com/mailveri/mailveri-mcp mailveri-mcp
• Environment Variables:
  • MAILVERI_API_KEY: YOUR_MAILVERI_API_KEY

Or add to .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"
      }
    }
  }
}

6. Configuration for Windsurf

Add to your Windsurf configuration file (~/.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"
      }
    }
  }
}

7. Configuration for OpenCode, Pi, Oh My Pi, Antigravity

Add to your tool's MCP configuration (opencode.json, ~/.pi/config.json, ~/.omp/mcp.json, or .gemini/antigravity/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"
      }
    }
  }
}

Environment Variables

Transport Options

Hosted Remote MCP (No Local Install)

Connect any Streamable HTTP or SSE MCP client directly to mcp.mailveri.com:

{
  "mcpServers": {
    "mailveri": {
      "url": "https://mcp.mailveri.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MAILVERI_API_KEY"
      }
    }
  }
}

Authentication Security: Always prefer sending your API key via the Authorization: Bearer YOUR_MAILVERI_API_KEY or X-API-Key: YOUR_MAILVERI_API_KEY HTTP header rather than query parameters (?api_key= / ?token=) so credentials are never exposed in client, browser, or reverse-proxy URL logs. Legacy SSE clients remain supported at https://mcp.mailveri.com/sse using Authorization: Bearer / X-API-Key headers (use ?api_key= only for older SSE clients that cannot set custom headers).

Self-Hosted / Local CLI

By default the CLI uses stdio transport (recommended for local desktop and CLI agents).

For local or self-hosted HTTP (Streamable HTTP at /mcp + SSE at /sse):

export MAILVERI_API_KEY="your_api_key"
mailveri-mcp --transport streamable-http --host 127.0.0.1 --port 8000

⚠️ Security: When MAILVERI_API_KEY or --api-key is pre-configured, self-hosted HTTP/SSE runs in single-tenant mode without per-request client authentication. Never bind to 0.0.0.0 or a public interface without placing an authenticating reverse proxy in front. In this self-hosted mode (a fixed key from --api-key or MAILVERI_API_KEY) the server only accepts a Host header of localhost, 127.0.0.1 or [::1], so a reverse proxy in front must keep nginx's default Host ($proxy_host) and must not set proxy_set_header Host $host.

Rate Limits

• Single email verification: 10 requests per second (up to 5 checks at a time)
• Batch verification: No per-request limit (emails are queued server-side)

Credit Exhaustion

If your account runs out of verification credits, mailveri_verify_email will return an error with message "Not enough credits to verify email". Check your balance with mailveri_get_balance and top up at MailVeri Pricing or your MailVeri Dashboard.

Local Development & Testing

Clone this repository and run locally:

git clone https://github.com/mailveri/mailveri-mcp.git
cd mailveri-mcp

# Install dependencies
pip install -e .

# Run unit tests (when tests/ is included in your checkout)
if [ -d tests ]; then python -m unittest discover -s tests; fi

# Test running the MCP server locally (stdio)
export MAILVERI_API_KEY="your_api_key"
python -m mailveri_mcp.server

Example Prompts for AI

Once connected, you can ask Claude or Cursor:

• "Check if alex@gmail.com and support@stripe.com are valid and deliverable."
• "How many email verification credits do I have left in MailVeri?"
• "Verify this list of 20 lead emails and let me know the batch status."
• "Get the result download link for my verification batch."
• "Give me a CSV download link for only the valid, deliverable emails from batch 'bX9K3LwZqP2YtR8vN4mQ'."

License

MIT License © 2026 MailVeri