byteplant-mcp

Byteplant MCP Server

Validate email addresses, phone numbers and postal addresses from any MCP client,
with unparalleled precision in 240+ countries worldwide.

Installation · Tools · Credentials · Usage · Compatibility · Resources

---

This is an MCP server that connects AI assistants such as Claude, Cursor and VS Code to the Byteplant validation APIs. Ask your assistant to check an email address, phone number or postal address, and it calls the matching Byteplant tool and reads back the result.

The server runs locally on your computer and talks to your MCP client over stdio.

Installation

The easiest way to run the server is with uv. uvx downloads the package and a suitable Python version automatically, so there is nothing else to install.

Add the server to your MCP client with one of the configurations below, and replace the placeholders with your API keys. You only need the keys for the services you use.

Claude Desktop

1. In Claude Desktop, go to Settings → Developer → Edit Config. This opens claude_desktop_config.json:

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

2. Add the Byteplant server:

   {
     "mcpServers": {
       "byteplant": {
         "command": "uvx",
         "args": ["byteplant-mcp@latest"],
         "env": {
           "EV_TOKEN": "<EMAIL VALIDATOR API KEY>",
           "PV_TOKEN": "<PHONE VALIDATOR API KEY>",
           "AV_TOKEN": "<ADDRESS VALIDATOR API KEY>"
         }
       }
     }
   }
   

3. Restart Claude Desktop.

Claude Code

claude mcp add \
  --env EV_TOKEN=<EMAIL VALIDATOR API KEY> \
  --env PV_TOKEN=<PHONE VALIDATOR API KEY> \
  --env AV_TOKEN=<ADDRESS VALIDATOR API KEY> \
  --transport stdio byteplant -- uvx byteplant-mcp@latest

Cursor

Add the same mcpServers entry as for Claude Desktop to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

VS Code

Add the server to .vscode/mcp.json in your project:

{
  "servers": {
    "byteplant": {
      "type": "stdio",
      "command": "uvx",
      "args": ["byteplant-mcp@latest"],
      "env": {
        "EV_TOKEN": "<EMAIL VALIDATOR API KEY>",
        "PV_TOKEN": "<PHONE VALIDATOR API KEY>",
        "AV_TOKEN": "<ADDRESS VALIDATOR API KEY>"
      }
    }
  }
}

Using pip instead of uv

pip install byteplant-mcp

This installs a byteplant-mcp command. Use its full path as the command, because desktop apps often don't see your shell's PATH (find it with which byteplant-mcp on macOS/Linux or where byteplant-mcp on Windows):

"command": "/full/path/to/byteplant-mcp"

Alternatively, run the module with the Python installation you installed it into:

"command": "/path/to/python",
"args": ["-m", "byteplant_mcp"]

Tools

Tool	What it does
validate_email	Checks whether an email address is deliverable and detects freemail providers
validate_phone	Validates a phone number and returns its line type, carrier codes, location and formats
validate_address	Validates and standardizes a postal address, with optional geocoding

Credentials

Each tool uses its own API key, passed to the server as an environment variable. Sign up for the service you need to get one:

Environment variable	Used by	Get an API key
EV_TOKEN	validate_email	Email Validator
PV_TOKEN	validate_phone	Phone Validator
AV_TOKEN	validate_address	Address Validator

You can manage your keys in your Byteplant account. If a key is missing, the matching tool tells the assistant which variable to set instead of calling the API.

Usage

Just ask your assistant in plain language, for example:

• "Is [email protected] a valid email address?"
• "Check whether +49 9874 322466 is a mobile or a landline number."
• "Validate this address and give me the standardized version: Heilsbronner Str. 4, 91564 Neuendettelsau, Germany."

The assistant fills in the tool parameters below. Every tool also has a timeout parameter, which sets how long the API may take to respond: 5–300 seconds, 10 by default.

validate_email - API Docs

Parameter	Required	Description
email	✅	The email address to validate

Output

Field	Description
status	Numeric result code, e.g. 200 for a valid address. See the full list of result codes.
category	Added by the server: VALID, SUSPECT, INVALID or INDETERMINATE, based on status (UNKNOWN for unlisted codes)
status_description	Added by the server: what the status code means
info	Short status description
details	Full status description
freemail	true if the address belongs to a freemail provider (Gmail, Yahoo, Outlook/Hotmail/Live, AOL, …)

validate_phone - API Docs

Parameter	Required	Description
phone	✅	The phone number to validate, in national format or in international format with a leading +
code		Two-letter ISO 3166-1 country code. Optional if the phone number is in international format.
locale		IETF language tag for geocoding results. Defaults to en-US.
mode		extensive (default) runs full validation. express runs static checks only and is faster.

Output

Field	Description
status	VALID_CONFIRMED, VALID_UNCONFIRMED, INVALID, DELAYED, RATE_LIMIT_EXCEEDED or API_KEY_INVALID_OR_DEPLETED
linetype	FIXED_LINE, MOBILE, VOIP, TOLL_FREE, PREMIUM_RATE, SHARED_COST, PERSONAL_NUMBER, PAGER, UAN or VOICEMAIL
location	Geographical location (city, county, state)
countrycode	Two-letter ISO 3166-1 country code
formatnational	Phone number in national format
formatinternational	Phone number in international format
mcc	Mobile country code, which identifies the mobile network operator (carrier)
mnc	Mobile network code, which identifies the mobile network operator (carrier)

validate_address - API Docs

Parameter	Required	Description
code	✅	Two-letter ISO 3166-1 country code. Use XX for international addresses.
street_adr	✅	Street, house number and building. May include the unit or apartment, or even the complete address.
street_num		House or building number, if it isn't part of street_adr
additional_info		Building, unit, apartment or floor
city		City or locality
postal_code		ZIP or postal code
state		State or province
geocoding		Whether to return coordinates for the address. Off by default.
locale		Output language for countries with more than one postal language. Use it only to translate addresses, and leave it empty for address validation.
charset		utf-8 (default) or us-ascii

Output

Field	Description
status	VALID: the address is correct and deliverable. SUSPECT: the address needs corrections to be deliverable, and a suggested correction is provided. INVALID: the address is not deliverable and can't be corrected automatically. Other values: DELAYED, NO_COUNTRY, RATE_LIMIT_EXCEEDED, API_KEY_INVALID_OR_DEPLETED, RESTRICTED, INTERNAL_ERROR
formattedaddress	Full address in standardized format
supplement	Additional address details (building, unit, apartment, suite)
street	Street in standardized format
streetnumber	Street number in standardized format
postalcode	ZIP or postal code in standardized format
city	City in standardized format
district	District in standardized format
county	County in standardized format
state	State or province in standardized format
country	Two-letter ISO 3166-1 country code
type	Address type: S for a street address, P for a P.O. box, pick-up or other delivery service
rdi	Residential Delivery Indicator: commercial or residential
diagnostics	Hints about errors in the address input. See the full list of diagnostic hints.
corrections	Hints about which parts of the address input were fixed. See the full list of correction hints.
latitude, longitude	Coordinates. Only returned for valid addresses when geocoding is on.

Compatibility

Requirement	Version
Python	3.10 or later (installed automatically by uvx)
MCP client	Any client that runs local stdio servers, e.g. Claude Desktop, Claude Code, Cursor, VS Code, Windsurf or OpenAI Codex

ChatGPT and Claude on the web or mobile only connect to remote (hosted) MCP servers, so they can't use this server yet.

Resources

• Model Context Protocol documentation
• Email Validator API documentation
• Phone Validator API documentation
• Address Validator API documentation
• Byteplant website
• Contact: [email protected]

License

MIT