# MailVeri MCP Server 🚀

[![Documentation](https://img.shields.io/badge/Docs-mailveri.com%2Fdocs%2Fmcp-purple?style=flat-square)](https://mailveri.com/docs/mcp/)
[![Website](https://img.shields.io/badge/Website-mailveri.com-blue?style=flat-square)](https://mailveri.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)

Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [MailVeri](https://mailveri.com) — 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](https://mailveri.com/docs/mcp/).  
> 📰 **Step-by-step Tutorial**: Read our comprehensive guide on [How to Verify Emails Directly in Claude, Cursor & Windsurf](https://mailveri.com/blog/mailveri-mcp-email-verification-ai-agents).

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

| Tool | Description |
| :--- | :--- |
| `mailveri_verify_email` | Verifies a single email address (returns `VALID`, `INVALID`, `DISPOSABLE`, `ROLE_ACCOUNT`, `CATCH_ALL`, `FULL_INBOX`, etc.). |
| `mailveri_get_balance` | Retrieves remaining verification credits for your MailVeri account. |
| `mailveri_verify_batch` | Queues a list of emails (minimum 2) for background distributed verification. |
| `mailveri_get_batch_status` | Checks progress percentage, status, and download links for a batch job. |
| `mailveri_download_batch_result` | Gets the download link for the completed batch results (full ZIP archive or custom filtered CSV by status/columns). |
| `mailveri_delete_batch` | Cancels or deletes a verification batch. |

---

## Quick Start

### 1. Get Your MailVeri API Key
Sign up or log in to the [MailVeri Dashboard](https://app.mailveri.com) and copy your API Key from **Dashboard → API Keys**:
👉 **[https://app.mailveri.com/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`

```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](https://docs.astral.sh/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:

```bash
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`:

```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`):

```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`:

```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`):

```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`):

```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

| Variable | Required | Default | Description |
| :--- | :---: | :--- | :--- |
| `MAILVERI_API_KEY` | **Yes** | — | Your MailVeri API Key. |
| `MAILVERI_BASE_URL` | No | `https://api.mailveri.com` | Base API endpoint (useful for staging or self-hosted instances). |

---

## Transport Options

By default the server uses **stdio** transport (recommended for Claude Desktop / Cursor).

For SSE transport (useful for remote or multi-client setups):

```bash
export MAILVERI_API_KEY="your_api_key"
mailveri-mcp --transport sse --host 127.0.0.1 --port 8000
```

> **⚠️ Security**: The SSE transport has no built-in authentication. Never bind to `0.0.0.0` or a public interface without placing an authenticating reverse proxy in front.

| Flag | Default | Description |
| :--- | :--- | :--- |
| `--transport` | `stdio` | Transport type: `stdio` or `sse` |
| `--host` | `127.0.0.1` | Host to bind for SSE transport |
| `--port` | `8000` | Port to bind for SSE transport |
| `--api-key` | — | API key (alternative to env var) |
| `--base-url` | `https://api.mailveri.com` | Base API URL |

---

## Rate Limits

- **Single email verification**: 1 request per second
- **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](https://mailveri.com/pricing) or your [MailVeri Dashboard](https://app.mailveri.com).

---

## Local Development & Testing

Clone this repository and run locally:

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

# Install dependencies
pip install -e .

# Run unit tests
python -m unittest discover -s tests

# 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](LICENSE) © 2026 MailVeri