io.github.byteplant-dev/byteplant-mcp

Official

by byteplant-dev · Python

An MCP server that provides Email, Phone and Address Validation Services from Byteplant

Validate email addresses, phone numbers and physical addresses.

README.md9 KBView on GitHub

Byteplant Validator MCP Server

Email, Phone Number, and Address Validation for the Model Context Protocol (MCP)

This package provides an MCP server that uses Byteplant’s Email-Validator, Phone-Validator, and Address-Validator APIs to deliver real-time live validation in any MCP-compatible client.

Features

Email validation
Phone number validation
Postal address validation
Fast studio MCP server
Local execution
Easy integration with Claude Desktop

Requirements

Python ≥ 3.12
A Byteplant API key (one for each validator). You can register to get one here
MCP Client (e.g. Claude Desktop)

MCP Configuration (Claude Desktop)

1. Installation

First, install the python module. You can use local installation (like venv) or global.

bash

pip install byteplant-mcp

2. Configuration

Next, add the MCP server to Claude configuration.

json

{
	"mcpServers": {
		"byteplant": {
			"command": "path/to/python/installation",
			"args": ["-m", "byteplant-mcp"],
			"env": {
				"EV_TOKEN": "<EMAIL VALIDATOR API TOKEN>",
				"PV_TOKEN": "<PHONE VALIDATOR API TOKEN>",
				"AV_TOKEN": "<ADDRESS VALIDATOR API TOKEN>"
			}
		}
	}
}

Byteplant's Email, Phone, and Address Validation Tools

1. `validate_email`

Real-Time Email Validation API

The Email Validation API returns the deliverability status and detailed information for the email that is provided as input.

API Endpoint

Parameter	Value
API URL	`https://api.email-validator.net/api/verify`
Method	`GET` or `POST`

Example API Request (GET)

https://api.email-validator.net/api/verify?EmailAddress=support@byteplant.com&APIKey=your API key

Input Parameters

Parameter	Description
EmailAddress	Email address to validate (string).
APIKey	Your API key (string).
Timeout	Timeout in seconds (int). Default: `10` (min `5`, max `300`).

API Result (JSON)

Parameter	Description
status	API result code. `401`, `118`, `119` indicate API errors:<br>• `401` → Email address missing<br>• `118` → Rate Limit Exceeded<br>• `119` → API Key Invalid or Depleted
info	Short status description.
details	Full status description.
freemail	Indicates if email is from a freemail provider (`true` / `false`).
ratelimit_remain	Remaining API requests before rate limit is reached (default: 100 requests / 300s).
ratelimit_seconds	Seconds remaining in the current rate-limit interval.

2. `validate_phone`

Real-Time Phone Validation API

The Real-Time Phone Verification API validates a single phone number in real-time.
It returns the status (VALID_CONFIRMED, VALID_UNCONFIRMED, INVALID) as well as details such as line type, carrier/operator, and location.

API Endpoint

Parameter	Value
API URL	`https://api.phone-validator.net/api/v2/verify`
Method	`GET` or `POST`

Example API Request (GET)

https://api.phone-validator.net/api/v2/verify?PhoneNumber=09874-322466&CountryCode=de&APIKey=your API key

Input Parameters

Parameter	Description
PhoneNumber	Phone number to validate (string, URL encoded). Accepts national format or international format with leading `+` (`+` → `%2B`, space → `%20`).
CountryCode	Two-letter ISO 3166-1 country code (string). Optional if number is in international format.
Locale	IETF language tag for geocoding (string). Optional; default: `en-US`.
Mode	Validation mode (string): `express` (static checks) or `extensive` (full validation). Optional; default: `extensive`.
APIKey	Your API key (string).
Timeout	Timeout in seconds (int). Optional; default: `10` (min `5`, max `300`).

API Result (JSON)

Parameter	Description
status	`VALID_CONFIRMED`, `VALID_UNCONFIRMED`, `INVALID`, `DELAYED`, `RATE_LIMIT_EXCEEDED`, `API_KEY_INVALID_OR_DEPLETED`
linetype	`FIXED_LINE`, `MOBILE`, `VOIP`, `TOLL_FREE`, `PREMIUM_RATE`, `SHARED_COST`, `PERSONAL_NUMBER`, `PAGER`, `UAN`, `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 (GSM/UMTS/LTE).
mnc	Mobile Network Code (GSM/UMTS/LTE).
ratelimit_remain	Remaining API requests before rate limit is hit (default limit: 100 requests / 300s).
ratelimit_seconds	Seconds remaining in current rate-limit interval.

3 `validate_address`

Real-Time Address Validation API

The Address Validation API returns the deliverability status and detailed information for the address that is provided as input.

API Endpoint

Parameter	Value
API URL	`https://api.address-validator.net/api/verify`
Method	`GET` or `POST`

Example API Request (GET)

https://api.address-validator.net/api/verify?StreetAddress=Heilsbronner Str. 4&City=Neuendettelsau&PostalCode=91564&CountryCode=de&Geocoding=true&APIKey=your API key

Input Parameters

Parameter	Description
CountryCode	Two-letter ISO 3166-1 country code (string). Use `'XX'` for international.
StreetAddress	Street/house number/building; may include unit/apartment info (string).
StreetNumber	House number/building (optional) (string).<br>House number/building may be part of `StreetAddress` or provided separately.
AdditionalAddressInfo	Building/unit/apt/floor etc. (optional) (string)
City	City or locality (city, district) (optional) (string)
PostalCode	ZIP / postal code (optional) (string)
State	State/province (optional) (string)
Geocoding	Enable Geocoding (`true`/`false`); default: `false` (optional)
Locale	Output language for countries with multiple postal languages—use only for translation; leave empty for validation. Default: local language (optional)
OutputCharset	Output character set: `us-ascii` or `utf-8` (default). (optional)
APIKey	Your API key (string)
Timeout	Timeout in seconds (default: 10s, min 5s, max 300s) (int)

General Usage Notes

Always use commas (",") to separate address elements where needed.

StreetAddress may contain the complete address; optional fields may be left empty.

China / Japan / Korea

Native script: Use big → small order for all fields.

English script: Use small → big order for all fields.

API Result (JSON)

Parameter	Description
status	VALID: address is correct and deliverable.<br>SUSPECT: address is incorrect and needs corrections to be deliverable, a suggested correction is provided.<br>INVALID: address is incorrect and not deliverable - either there is no match at all in the reference data or the address is ambiguous and there are many matches. In these cases automatic correction suggestions are not available.<br>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 / apt / suite etc.).
street	Street address in standardized format.
streetnumber	Street number in standardized format.
postalcode	ZIP / postal code in standardized format.
city	City in standardized format.
type	Address type: S = Street address / P = P.O. Box, Pick-Up, or other delivery service.
rdi	Residential Delivery Indicator (Commercial / Residential).
district	District in standardized format.
county	County in standardized format.
state	State / province in standardized format.
country	Two-letter ISO 3166-1 country code.
latitude	Latitude (for valid addresses if Geocoding is enabled).
longitude	Longitude (for valid addresses if Geocoding is enabled).
diagnostics	Detailed diagnostic hints, indicating errors in the address input.
corrections	Detailed correction hints, indicating which parts of the address input have been fixed.
ratelimit_remain	Number of API requests remaining before the API rate limit is reached (default API rate limit allows 100 API requests in 300s).
ratelimit_seconds	Number of seconds remaining in the current rate limit interval.

Environment Variables

EV_TOKEN: Your Email Validator API Token
PV_TOKEN: Your Phone Validator API Token
AV_TOKEN: Your Address Validator API Token You may use only the tokens for the services you use (e.g. only Email Validator), in that case leave the others tokens empty.

Contact

Website: https://www.byteplant.com
Get your API key: https://www.byteplant.com/account/
Email: contact@byteplant.com

Install

Configuration

Environment variables

EV_TOKENsecret

Email Validator API Token

AV_TOKENsecret

Address Validator API Token

PV_TOKENsecret

Phone Validator API Token

claude_desktop_config.json

{
  "mcpServers": {
    "byteplant-mcp": {
      "command": "uvx",
      "args": [
        "byteplant-mcp"
      ],
      "env": {
        "EV_TOKEN": "<YOUR_EV_TOKEN>",
        "AV_TOKEN": "<YOUR_AV_TOKEN>",
        "PV_TOKEN": "<YOUR_PV_TOKEN>"
      }
    }
  }
}

Byteplant Validator MCP Server

Features

Requirements

MCP Configuration (Claude Desktop)

1. Installation

2. Configuration

Byteplant's Email, Phone, and Address Validation Tools

1. validate_email

Real-Time Email Validation API

API Endpoint

Example API Request (GET)

Input Parameters

API Result (JSON)

2. validate_phone

Real-Time Phone Validation API

API Endpoint

Example API Request (GET)

Input Parameters

API Result (JSON)

3 validate_address

Real-Time Address Validation API

API Endpoint

Example API Request (GET)

Input Parameters

General Usage Notes

China / Japan / Korea

API Result (JSON)

Environment Variables

Contact

Install

Configuration

1. `validate_email`

2. `validate_phone`

3 `validate_address`