# Mailveri MCP Server 🚀

Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Mailveri](https://mailveri.com) — Fast, accurate, and privacy-friendly email verification.

This server enables AI assistants (**Claude Desktop**, **Cursor**, **Antigravity**, **Windsurf**, 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 verification result zip. |
| `mailveri_delete_batch` | Cancels or deletes a verification batch. |

---

## Quick Start

### 1. Get Your Mailveri API Key
Sign up or log in to [Mailveri](https://mailveri.com) and copy your `Auth-Token` at:
👉 **[https://mailveri.com/api-key/](https://mailveri.com/api-key/)**

---

### 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_AUTH_TOKEN_HERE"
      }
    }
  }
}
```

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

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_AUTH_TOKEN_HERE"
      }
    }
  }
}
```

---

### 4. Configuration for Antigravity / Other MCP Clients

Add to your MCP config (e.g. `.gemini/settings.json`, `.mcp.json`, or equivalent):

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

---

## Environment Variables

| Variable | Required | Default | Description |
| :--- | :---: | :--- | :--- |
| `MAILVERI_API_KEY` | **Yes** | — | Your Mailveri API Key (`Auth-Token`). |
| `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_token"
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.com](https://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_token"
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."*

---

## License

[MIT License](LICENSE) © 2026 Mailveri