BillionVerify

Official11 tools

by BillionVerify · TypeScript

Email verification for AI agents: verify single or bulk emails, check credits and history.

io.github.BillionVerify/billionverify-mcp MCP Server

This MCP server provides email verification capabilities for AI agents. It can verify a single email address or perform bulk verification. It also supports checking available credits and reviewing verification history, based on the server’s description.

🛠️ Key Features

Verify single emails
Verify bulk email lists
Check verification credits
Access verification history

🚀 Use Cases

Validate user-provided email addresses before agent actions
Bulk-clean or verify datasets used by AI agents
Audit prior verification activity using history
Enforce credit limits by checking available credits

⚡ Developer Benefits

Clear support for both single and bulk verification workflows
Credits visibility to manage usage constraints
History support for troubleshooting and auditing

⚠️ Limitations

No additional tool details (e.g., specific tool names or parameters) are provided in the available source data

Topics

email-marketingemail-validationemail-validation-apiemail-verificationemail-verifiermcp-serveremailemail-checkeremail-phishingemail-validatorcold-emailemail-sender

Captured live from the server via tools/list.

create_webhook

Create a webhook endpoint for verification lifecycle notifications.

Parameters2

events	array	required	The webhook event types to subscribe to.
url	string	required	The HTTPS endpoint that should receive webhook deliveries.

Raw schema

{
  "type": "object",
  "properties": {
    "events": {
      "description": "The webhook event types to subscribe to.",
      "items": {
        "enum": [
          "file.completed",
          "file.failed"
        ],
        "type": "string"
      },
      "minItems": 1,
      "type": "array"
    },
    "url": {
      "description": "The HTTPS endpoint that should receive webhook deliveries.",
      "type": "string"
    }
  },
  "required": [
    "url",
    "events"
  ]
}

delete_webhook

Permanently delete a webhook endpoint by identifier. The endpoint stops receiving notifications immediately.

Parameters1

webhook_id

string

required

The webhook identifier to delete.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "description": "The webhook identifier to delete.",
      "type": "string"
    }
  },
  "required": [
    "webhook_id"
  ]
}

get_account_balance

Get the current credit balance for the authenticated account.

Parameters

No parameters.

Raw schema

{
  "type": "object"
}

get_download_url

Get a signed download URL for completed results, or CSV content when filtered or rebuilt from history.

Parameters7

catchall	boolean	optional	Include results marked as catchall.
disposable	boolean	optional	Include results marked as disposable.
invalid	boolean	optional	Include results marked as invalid.
job_id	string	required	The completed verification job identifier.
role	boolean	optional	Include results marked as role-based addresses.
unknown	boolean	optional	Include results marked as unknown.
valid	boolean	optional	Include results marked as valid.

Raw schema

{
  "type": "object",
  "properties": {
    "catchall": {
      "default": false,
      "description": "Include results marked as catchall.",
      "type": "boolean"
    },
    "disposable": {
      "default": false,
      "description": "Include results marked as disposable.",
      "type": "boolean"
    },
    "invalid": {
      "default": false,
      "description": "Include results marked as invalid.",
      "type": "boolean"
    },
    "job_id": {
      "description": "The completed verification job identifier.",
      "type": "string"
    },
    "role": {
      "default": false,
      "description": "Include results marked as role-based addresses.",
      "type": "boolean"
    },
    "unknown": {
      "default": false,
      "description": "Include results marked as unknown.",
      "type": "boolean"
    },
    "valid": {
      "default": false,
      "description": "Include results marked as valid.",
      "type": "boolean"
    }
  },
  "required": [
    "job_id"
  ]
}

get_task_status

Get the current status of an asynchronous verification task.

Parameters1

task_id

string

required

The task or job identifier returned by a previous verification request.

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "description": "The task or job identifier returned by a previous verification request.",
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ]
}

get_verification_history

List verification history for the authenticated account.

Parameters2

limit	number	optional	The number of history records to return per page.
page	number	optional	The page number to retrieve.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 20,
      "description": "The number of history records to return per page.",
      "maximum": 100,
      "minimum": 1,
      "type": "number"
    },
    "page": {
      "default": 1,
      "description": "The page number to retrieve.",
      "minimum": 1,
      "type": "number"
    }
  }
}

get_verification_stats

Get aggregated verification statistics for the authenticated account.

Parameters1

period

string

optional

The reporting period to query.

Raw schema

{
  "type": "object",
  "properties": {
    "period": {
      "default": "30d",
      "description": "The reporting period to query.",
      "enum": [
        "7d",
        "30d",
        "90d",
        "1y"
      ],
      "type": "string"
    }
  }
}

health_check

Check the health of the BillionVerify MCP server.

Parameters

No parameters.

Raw schema

{
  "type": "object"
}

list_webhooks

List all webhook endpoints configured for the authenticated account.

Parameters

No parameters.

Raw schema

{
  "type": "object"
}

verify_batch_emails

Verify 1 to 50 email addresses in one request and return a verdict for each. Split longer lists into chunks of 50. Uses credits from the connected BillionVerify account.

Parameters2

check_smtp	boolean	optional	Whether to perform SMTP checks for each email address.
emails	array	required	The email addresses to verify, with a minimum of 1 item and a maximum of 50 items.

Raw schema

{
  "type": "object",
  "properties": {
    "check_smtp": {
      "default": false,
      "description": "Whether to perform SMTP checks for each email address.",
      "type": "boolean"
    },
    "emails": {
      "description": "The email addresses to verify, with a minimum of 1 item and a maximum of 50 items.",
      "items": {
        "minLength": 3,
        "type": "string"
      },
      "maxItems": 50,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "emails"
  ]
}

verify_single_email

Verify whether a single email address can receive mail. Checks syntax and the domain's mail servers, and optionally the mailbox over SMTP. Uses credits from the connected BillionVerify account.

Parameters3

check_smtp	boolean	optional	Whether to perform an SMTP check in addition to syntax and domain checks.
email	string	required	The email address to verify.
force_refresh	boolean	optional	Whether to bypass cached results and force a fresh verification.

Raw schema

{
  "type": "object",
  "properties": {
    "check_smtp": {
      "default": false,
      "description": "Whether to perform an SMTP check in addition to syntax and domain checks.",
      "type": "boolean"
    },
    "email": {
      "description": "The email address to verify.",
      "type": "string"
    },
    "force_refresh": {
      "default": false,
      "description": "Whether to bypass cached results and force a fresh verification.",
      "type": "boolean"
    }
  },
  "required": [
    "email"
  ]
}

README.md4 KBView on GitHub

BillionVerify MCP Server — TypeScript

Connect any AI assistant to BillionVerify email verification via the Model Context Protocol. Built with the official MCP TypeScript SDK.

Option 1 — Hosted Server (No Installation)

Use BillionVerify's hosted MCP server. There is nothing to install and no API key to paste: you sign in with your BillionVerify account over OAuth, and the connection is tied to that account.


Server URL	`https://mcp.billionverify.com/mcp`
Transport	Streamable HTTP
Authentication	OAuth 2.1 (sign in with your BillionVerify account)

The hosted server does not accept API keys (?api_key=, BV-API-KEY or Authorization: Bearer <api key> are all rejected). If you want to use an API key, use Option 2.

Detailed step-by-step guide: docs/connect-chatgpt-claude.md.

ChatGPT (web)

Settings → Apps & Connectors → Advanced settings → turn on Developer mode.
Settings → Apps & Connectors → Create.
Name BillionVerify, MCP server URL https://mcp.billionverify.com/mcp, authentication OAuth → create.
Sign in to BillionVerify in the window that opens and approve access.
In a new chat, click + → Developer mode → enable BillionVerify.

Claude (claude.ai / Claude Desktop)

Customize → Connectors → + → Add custom connector.
Name BillionVerify, URL https://mcp.billionverify.com/mcp → Add (leave Advanced settings empty).
Click Connect, sign in to BillionVerify and approve access.
In a chat, click + → Connectors and make sure BillionVerify is on.

Team / Enterprise: an Owner adds the connector under Organization settings → Connectors, then each member clicks Connect.

Claude Code

bash

claude mcp add --transport http billionverify https://mcp.billionverify.com/mcp

Then run /mcp inside Claude Code, select billionverify and finish the sign-in in your browser.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), then click Connect next to the server in Settings → MCP:

json

{
  "mcpServers": {
    "billionverify": {
      "url": "https://mcp.billionverify.com/mcp"
    }
  }
}

Option 2 — Self-Hosted (TypeScript / Node.js)

Run your own MCP server using this TypeScript implementation.

Prerequisites

Node.js 18+

Run via npx (no install)

bash

BILLIONVERIFY_API_KEY=your_api_key npx billionverify-mcp

Claude Desktop config (self-hosted)

json

{
  "mcpServers": {
    "billionverify": {
      "command": "npx",
      "args": ["-y", "billionverify-mcp"],
      "env": {
        "BILLIONVERIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Install globally

bash

npm install -g billionverify-mcp
billionverify-mcp

Install from source

bash

git clone https://github.com/BillionVerify/billionverify-mcp.git
cd billionverify-mcp
npm install
npm run build
npm start

Environment Variables

Variable	Description	Default
`BILLIONVERIFY_API_KEY`	Your BillionVerify API key	—
`BILLIONVERIFY_API_URL`	API base URL override	`https://api.billionverify.com`

Available Tools

Tool	Description
`verify_single_email`	Verify a single email address in real-time
`verify_batch_emails`	Verify up to 50 emails in one request
`get_account_balance`	Check your credit balance
`get_verification_history`	List verification history (paginated)
`get_verification_stats`	Aggregated statistics for 7d / 30d / 90d / 1y
`get_task_status`	Poll the status of an async file verification job
`get_download_url`	Get download URL for results with status filters
`create_webhook`	Subscribe to file completion events
`list_webhooks`	List all configured webhooks
`delete_webhook`	Remove a webhook
`health_check`	Check server health

License

MIT

Install

Tools (11)

create_webhookdelete_webhookget_account_balanceget_download_urlget_task_statusget_verification_historyget_verification_statshealth_check

Configuration

Environment variables

BILLIONVERIFY_API_KEYrequiredsecret

Your BillionVerify API key

BILLIONVERIFY_API_URLdefault https://api.billionverify.com

API base URL override

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "billionverify-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "billionverify-mcp@1.1.1"
      ],
      "env": {
        "BILLIONVERIFY_API_KEY": "<YOUR_BILLIONVERIFY_API_KEY>",
        "BILLIONVERIFY_API_URL": "https://api.billionverify.com"
      }
    }
  }
}

io.github.BillionVerify/billionverify-mcp MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

create_webhook

delete_webhook

get_account_balance

get_download_url

get_task_status

get_verification_history

get_verification_stats

health_check

list_webhooks

verify_batch_emails

verify_single_email

BillionVerify MCP Server — TypeScript

Option 1 — Hosted Server (No Installation)

ChatGPT (web)

Claude (claude.ai / Claude Desktop)

Claude Code

Cursor

Option 2 — Self-Hosted (TypeScript / Node.js)

Prerequisites

Run via npx (no install)

Claude Desktop config (self-hosted)

Install globally

Install from source

Environment Variables

Available Tools

License

Install

Configuration

Related servers