How do I use truelist-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@truelist-mcp check if jane.doe@company.com is deliverable" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

truelist-mcp

Official

by Truelist-Labs

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

truelist-mcp

Free tier 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.

Related MCP server: email-verify

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": "user@example.com"
}

Output:

{
  "email": "user@example.com",
  "state": "ok",
  "sub_state": "email_ok",
  "suggestion": null,
  "domain": "example.com",
  "canonical": "user@example.com",
  "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": [
    "user@example.com",
    "test@invalid.example",
    "hello@gmail.com"
  ]
}

Output:

[
  {
    "email": "user@example.com",
    "state": "ok",
    "sub_state": "email_ok",
    "is_valid": true
  },
  {
    "email": "test@invalid.example",
    "state": "email_invalid",
    "sub_state": "failed_mx_check",
    "is_valid": false
  },
  {
    "email": "hello@gmail.com",
    "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": "you@company.com",
  "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

Restart your AI assistant after changing the MCP configuration
Check that npx truelist-mcp runs without errors when TRUELIST_API_KEY is set
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

Available Tools

3 tools

check_accountAInspect

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the disclosure burden. "Check" implies a read-only, self-scoped lookup and the field list tells the agent what comes back, but nothing is said about authentication requirements, whether plan limits or quota details are included, or rate limiting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence that front-loads the action and then the payload. Every clause earns its place and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description usefully compensates by naming the returned fields. For a zero-param, self-scoped read this is close to complete; only auth/permission behavior and any plan-related caveats would have added value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly does not invent arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource ("Check your Truelist account info") and enumerates the exact fields surfaced (name, email, plan, admin status), so an agent knows precisely what this returns. It does not explicitly contrast itself with the siblings, though those are email-validation tools in an adjacent domain, making the distinction fairly obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call this to inspect the current account's profile and plan. There is no explicit when-to-use, when-not-to-use, or named alternative, but the sibling tools (validate_email/validate_emails) are functionally unrelated so no routing ambiguity is created.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_emailBInspect

Validate an email address for deliverability using Truelist. Returns state (ok/email_invalid/risky/accept_all/unknown), sub_state, and metadata like domain, canonical, mx_record, first_name, last_name, and verified_at.

ParametersJSON Schema

Name	Required	Description	Default
`email`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations and no output schema, the description usefully enumerates the possible return states (ok/email_invalid/risky/accept_all/unknown) and the returned metadata fields, which is real behavioral value. However, it omits auth/permission requirements, rate limits or credit costs, and what distinguishes 'risky' from 'accept_all' from a caller's standpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core purpose and followed by the response contract. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter validation tool with no output schema and no annotations, the description does the essential work by enumerating return states and metadata fields. It falls short only on operational context (auth, cost, error semantics) that a caller might still need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single 'email' parameter has no description, so the description carries the burden — yet 'an email address' merely restates the parameter name without format, normalization, or canonicalization behavior. The parameter is self-evident, which keeps this from being a 1, but nothing is added beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Validate an email address for deliverability') plus the underlying provider (Truelist), which is unambiguous. It hints at the singular scope versus the sibling validate_emails, but never names or contrasts the batch variant, so sibling differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over validate_emails (batch) or check_account, and no prerequisites, quotas, or exclusions are stated. The only contextual signal is the word 'deliverability', which an agent must interpret on its own.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_emailsAInspect

Validate multiple email addresses for deliverability in a single batch. Returns an array of results with state and sub_state for each email. Maximum 50 emails per request.

ParametersJSON Schema

Name	Required	Description	Default
`emails`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It mentions the return shape ('state and sub_state'), which is helpful, but does not state whether this is a read-only operation, what happens when emails exceed 50, rate limits, or error behavior for invalid addresses. Significant gaps remain for a validation tool with no structured safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, information-dense sentences. The purpose is front-loaded, followed by output structure and a key constraint. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple batch validation tool with no output schema, the description covers the core operation and return shape, but omits error handling, rate limits, and when to prefer sibling tools. It is adequate but leaves clear gaps that could affect correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It states the parameter accepts multiple emails and enforces a maximum of 50, which matches the schema's maxItems, but does not explain the email format or what happens if fewer than 1 is provided (minItems). Nonetheless, the description provides meaningful constraint info beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Validate') and resource ('email addresses for deliverability'), and the batch nature distinguishes it from likely sibling validate_email. It also clarifies the output structure ('array of results with state and sub_state').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus validate_email or check_account. The batch limitation (max 50) is stated, but that's a constraint, not usage context. There are no exclusions or alternative suggestions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.1Oct 15, 2026
- First observedcheck_account
- First observedvalidate_email
- First observedvalidate_emails

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-10-15 16:30 across 3 tools

Disambiguation4/5

validate_email and validate_emails are distinct (single vs. batch) and check_account is unrelated, so boundaries are mostly clear. The singular/plural naming is the only spot where an agent could momentarily hesitate.

Naming Consistency5/5

All three tools follow a consistent verb_noun snake_case pattern (validate_email, validate_emails, check_account). Predictable and readable throughout.

Tool Count4/5

Three tools is fairly minimal but matches the narrow scope of an email validation service. It is not bloated, though the surface is lean enough to feel slightly thin.

Completeness4/5

The domain (email deliverability validation plus account info) is well covered: single validation, batch validation, and account checking. No update/delete lifecycle applies here, so the surface is nearly complete for its purpose.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-server AOAuth
com.pingvalid
Email validation for Claude and any MCP client — verdicts with evidence and bulk jobs.
Email Customer Support
2
email A
dev.primitive
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email Communication
142
BillionVerify A
io.github.BillionVerify
Email verification for AI agents: verify single or bulk emails, check credits and history.
Email Security
111
emailverifier.devOAuth
io.github.usamaejaz
Verify emails and domains for routing, disposable providers, role accounts, and SMTP risk.
Email Security
1

Related MCP Servers

SendGrid MCP Server
Email CRM
FINCH285
A
license
Not graded
quality
D
maintenance
Enables AI models to send emails, manage contacts, and interact with SendGrid's email platform via MCP.
Updated a year ago (2025-09-18 23:42 UTC)
1
MIT
email-verify
Email Marketing
Baneado98
A
license
A
quality
D
maintenance
Enables real-time email verification via MCP tools, checking syntax, MX, disposable domains, and optional SMTP probe to determine deliverability with a VALID/RISKY/INVALID verdict.
Updated 4 months ago (2026-06-22 18:05 UTC)
2
9 npm
MIT
InboxValid MCP Server
Email Security
siddreddy07
F
license
Not graded
quality
C
maintenance
Provides email verification as an MCP tool, checking format, disposable domains, and mail server availability with structured results.
Updated 2 months ago (2026-08-12 11:53 UTC)
-
Email Verifier MCP Server
Email Marketing
iguha0
F
license
Not graded
quality
B
maintenance
Enables AI agents to verify email addresses in real-time, checking syntax, DNS, MX records, and SMTP handshake, returning verdicts and deliverability scores without sending actual emails.
Updated a month ago (2026-09-17 19:44 UTC)
-