# MailVeri MCP Server 🚀

[![PyPI](https://img.shields.io/pypi/v/mailveri-mcp?style=flat-square&color=006dad)](https://pypi.org/project/mailveri-mcp/)
[![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)
[![Smithery](https://img.shields.io/badge/Smithery-mailveri%2Fmailveri--mcp-brightgreen?style=flat-square)](https://registry.smithery.ai/servers/mailveri/mailveri-mcp)
[![Glama](https://img.shields.io/badge/Glama-Listed-orange?style=flat-square)](https://glama.ai/mcp/servers/mailveri/mailveri-mcp)
[![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/).  
> 🧠 **Agent Skill (`SKILL.md`)**: Includes [`SKILL.md`](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](https://mailveri.com/blog/mailveri-mcp-email-verification-ai-agents).  
> ⚡ **Official Registries**: Published on [PyPI (`mailveri-mcp`)](https://pypi.org/project/mailveri-mcp/), listed on [Glama.ai](https://glama.ai/mcp/servers/mailveri/mailveri-mcp), and indexed in the [Smithery Registry (`mailveri/mailveri-mcp`)](https://registry.smithery.ai/servers/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

| Tool | Safety Hints (`ToolAnnotations`) | Description |
| :--- | :--- | :--- |
| `mailveri_verify_email` | `readOnly: false`, `destructive: false` | Verifies a single email address (returns `VALID`, `INVALID`, `DISPOSABLE`, `ROLE_ACCOUNT`, `CATCH_ALL`, `FULL_INBOX`, `UNKNOWN`, plus `credits_used`, `quality_score`, `is_forwarding`, and `balance`). |
| `mailveri_get_balance` | `readOnly: true`, `idempotent: true` | Retrieves remaining verification credits (plus `daily_limit`, `daily_remaining`, `daily_used` on daily-quota plans). |
| `mailveri_verify_batch` | `readOnly: false`, `destructive: false` | Queues a list of emails (minimum 2) for background distributed verification. |
| `mailveri_get_batch_status` | `readOnly: true`, `idempotent: true` | Checks progress percentage, status (`QUEUED`, `PROCESSING`, `DONE`, `CANCELED`, `MERGED`), and download links for a batch job. |
| `mailveri_download_batch_result` | `readOnly: true`, `idempotent: true` | Gets the download link for completed batch results (full ZIP archive or filtered CSV; CSV `status` defaults to `VALID,ROLE_ACCOUNT` when omitted). |
| `mailveri_delete_batch` | `destructive: true`, `idempotent: true` | Deletes a finished or canceled verification batch. |

---

## Quick Start

### 1-Click Install via Smithery
Add to your MCP client in one command:
```bash
npx -y smithery mcp add mailveri/mailveri-mcp
```

---

### 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": [
        "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 mailveri-mcp
```

Or add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "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": [
        "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 mailveri-mcp`
- **Environment Variables**:
  - `MAILVERI_API_KEY`: `YOUR_MAILVERI_API_KEY`

Or add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "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": [
        "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": [
        "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

### Hosted Remote MCP (No Local Install)

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

```json
{
  "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`):

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

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

---

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