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)

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

Claude (claude.ai / Claude Desktop)

1. Customize → Connectors → + → Add custom connector.
2. Name BillionVerify, URL https://mcp.billionverify.com/mcp → Add (leave Advanced settings empty).
3. Click Connect, sign in to BillionVerify and approve access.
4. 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

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:

{
  "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)

BILLIONVERIFY_API_KEY=your_api_key npx billionverify-mcp

Claude Desktop config (self-hosted)

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

Install globally

npm install -g billionverify-mcp
billionverify-mcp

Install from source

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