truelist-mcp

MCP (Model Context Protocol) server for Truelist email validation. Lets AI assistants like Claude, Cursor, and VS Code Copilot validate email addresses for deliverability.

What is this?

This package exposes Truelist's email validation API as MCP tools. Once configured, your AI assistant can:

• Check if an email address is valid and deliverable
• Validate batches of emails at once
• Check your Truelist account info and plan

Start free — 100 validations + 10 enhanced credits, no credit card required. Get your API key → Works with the free plan.

Installation

npm install -g truelist-mcp

Or run directly with npx:

npx truelist-mcp

Configuration

You need a Truelist API key. Get one at truelist.io.

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "truelist": {
      "command": "npx",
      "args": ["truelist-mcp"],
      "env": {
        "TRUELIST_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Add to your .claude/settings.json or run:

claude mcp add truelist -- npx truelist-mcp

Then set the environment variable:

export TRUELIST_API_KEY=your-api-key

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "truelist": {
      "command": "npx",
      "args": ["truelist-mcp"],
      "env": {
        "TRUELIST_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your VS Code settings (.vscode/mcp.json in your project):

{
  "servers": {
    "truelist": {
      "command": "npx",
      "args": ["truelist-mcp"],
      "env": {
        "TRUELIST_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

validate_email

Validate a single email address for deliverability.

Input:

{
  "email": "[email protected]"
}

Output:

{
  "email": "[email protected]",
  "state": "ok",
  "sub_state": "email_ok",
  "suggestion": null,
  "domain": "example.com",
  "canonical": "[email protected]",
  "mx_record": "mx.example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "verified_at": "2026-02-21T12:00:00Z",
  "is_valid": true,
  "is_deliverable": true
}

States: | State | Meaning | |-------|---------| | ok | Email is deliverable | | email_invalid | Email is not deliverable | | risky | Email may be deliverable but has risk factors | | accept_all | Domain accepts all addresses; deliverability uncertain | | unknown | Could not determine deliverability |

Sub-states: | Sub-state | Meaning | |-----------|---------| | email_ok | No issues found | | accept_all | Domain accepts all addresses | | is_disposable | Temporary/disposable email | | is_role | Role-based address (info@, support@, etc.) | | failed_mx_check | Domain has no mail server | | failed_smtp_check | SMTP verification failed | | failed_spam_trap | Known spam trap address | | failed_no_mailbox | Mailbox does not exist | | failed_greylisted | Server temporarily rejected | | failed_syntax_check | Invalid email syntax | | unknown | Could not determine sub-state |

validate_emails

Validate multiple email addresses in a single batch (max 50).

Input:

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

Output:

[
  {
    "email": "[email protected]",
    "state": "ok",
    "sub_state": "email_ok",
    "is_valid": true
  },
  {
    "email": "[email protected]",
    "state": "email_invalid",
    "sub_state": "failed_mx_check",
    "is_valid": false
  },
  {
    "email": "[email protected]",
    "state": "ok",
    "sub_state": "email_ok",
    "is_valid": true
  }
]

check_account

Check your Truelist account info including name, email, plan, and admin status.

Input: none

Output:

{
  "email": "[email protected]",
  "name": "Your Name",
  "uuid": "a3828d19-...",
  "timeZone": "America/New_York",
  "isAdminRole": true,
  "paymentPlan": "pro"
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TRUELIST_API_KEY | Yes | Your Truelist API key from truelist.io |

Troubleshooting

"TRUELIST_API_KEY environment variable is required"

The server requires a TRUELIST_API_KEY environment variable. Make sure it's set in your MCP configuration's env block or exported in your shell.

Tool not showing up in Claude/Cursor

1. Restart your AI assistant after changing the MCP configuration
2. Check that npx truelist-mcp runs without errors when TRUELIST_API_KEY is set
3. Verify the config file path is correct for your platform

Authentication errors

Verify your API key is correct and active at truelist.io.

Rate limiting

Truelist enforces rate limits on the API. If you hit rate limits, the SDK will automatically retry with exponential backoff. For batch validation, emails are validated concurrently so large batches may trigger rate limits.

Getting Started

Sign up for a free Truelist account to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.

License

MIT