Validates email addresses, phone numbers, and postal addresses across 240+ countries via Byteplant APIs.
Also known as byteplant-devops/byteplant-mcp
- Stars
- 1
- Tools
- 3
- Downloads, 30 days
- 256
- Latest version
- 1.1.1
- Last commit
- Oct 21, 2026
- License
- MIT
What is Byteplant MCP?
Byteplant validates email addresses, phone numbers, and postal addresses across 240+ countries via Byteplant APIs. It exposes 3 tools, such as validate_email, validate_phone, validate_address.
Summary generated from the project's README
About Byteplant MCP server
Verifying contact information from within your development environment is what byteplant-mcp enables for developers using AI assistants. By connecting to Byteplant APIs, this server allows tools like Claude Desktop, Cursor, and VS Code to check the accuracy of email addresses, phone numbers, and postal addresses across more than 240 countries.
The server runs locally on your machine using the stdio transport method. To use it, you must provide specific API keys for the services you need, namely EV_TOKEN for email, PV_TOKEN for phone, and AV_TOKEN for addresses. It is designed for local MCP clients and is not compatible with web-based versions of ChatGPT or Claude.
Users can interact with three specific tools: validate_email to detect deliverability and freemail providers, validate_phone to identify line types and carriers, and validate_address to standardize postal data with optional geocoding. The server can be installed easily using uvx or pip.
What you can do with it
- 1Verify email deliverabilityCheck if a specific email address is valid and whether it belongs to a free provider like Gmail.
- 2Identify phone line typesDetermine if a phone number is a mobile, landline, or VOIP number and find its carrier.
- 3Standardize postal addressesConvert a messy address into a standardized format and retrieve its geographic coordinates.
Written from the project's README. Every use case is checked against a quote from it.
How to install Byteplant MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Byteplant MCP in Claude Code
$ claude mcp add --env 'AV_TOKEN=<YOUR_AV_TOKEN>' --env 'EV_TOKEN=<YOUR_EV_TOKEN>' --env 'PV_TOKEN=<YOUR_PV_TOKEN>' byteplant-mcp -- uvx byteplant-mcpInstall Byteplant MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"byteplant-mcp": {
"command": "uvx",
"args": [
"byteplant-mcp"
],
"env": {
"AV_TOKEN": "<YOUR_AV_TOKEN>",
"EV_TOKEN": "<YOUR_EV_TOKEN>",
"PV_TOKEN": "<YOUR_PV_TOKEN>"
}
}
}
}Install Byteplant MCP in VS Code
.vscode/mcp.json
{
"servers": {
"byteplant-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"byteplant-mcp"
],
"env": {
"AV_TOKEN": "<YOUR_AV_TOKEN>",
"EV_TOKEN": "<YOUR_EV_TOKEN>",
"PV_TOKEN": "<YOUR_PV_TOKEN>"
}
}
}
}Install Byteplant MCP in VS Code CLI
$ code --add-mcp '{"name":"byteplant-mcp","type":"stdio","command":"uvx","args":["byteplant-mcp"],"env":{"AV_TOKEN":"<YOUR_AV_TOKEN>","EV_TOKEN":"<YOUR_EV_TOKEN>","PV_TOKEN":"<YOUR_PV_TOKEN>"}}'Install Byteplant MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"byteplant-mcp": {
"command": "uvx",
"args": [
"byteplant-mcp"
],
"env": {
"AV_TOKEN": "<YOUR_AV_TOKEN>",
"EV_TOKEN": "<YOUR_EV_TOKEN>",
"PV_TOKEN": "<YOUR_PV_TOKEN>"
}
}
}
}Install Byteplant MCP in Codex
$ codex mcp add byteplant-mcp --env 'AV_TOKEN=<YOUR_AV_TOKEN>' --env 'EV_TOKEN=<YOUR_EV_TOKEN>' --env 'PV_TOKEN=<YOUR_PV_TOKEN>' -- uvx byteplant-mcpInstall Byteplant MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.byteplant-mcp] command = "uvx" args = ["byteplant-mcp"] [mcp_servers.byteplant-mcp.env] AV_TOKEN = "<YOUR_AV_TOKEN>" EV_TOKEN = "<YOUR_EV_TOKEN>" PV_TOKEN = "<YOUR_PV_TOKEN>"
Install Byteplant MCP in Gemini CLI
$ gemini mcp add -s user -e 'AV_TOKEN=<YOUR_AV_TOKEN>' -e 'EV_TOKEN=<YOUR_EV_TOKEN>' -e 'PV_TOKEN=<YOUR_PV_TOKEN>' byteplant-mcp uvx -- byteplant-mcpInstall Byteplant MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"byteplant-mcp": {
"command": "uvx",
"args": [
"byteplant-mcp"
],
"env": {
"AV_TOKEN": "<YOUR_AV_TOKEN>",
"EV_TOKEN": "<YOUR_EV_TOKEN>",
"PV_TOKEN": "<YOUR_PV_TOKEN>"
}
}
}
}Byteplant MCP tools 3
Read from the server with tools/listvalidate_emailRead-onlyValidate an email address and return info about it. Result fields: - status (int): API result code. 401, 118 and 119 status codes indicate API errors: 401 -> info: 'Email address missing' 118 -> info: 'Rate Limit Exceeded' 119 -> info: 'API Key Invalid or Depleted' - info (string): short status description - details (string): full status description - freemail (boolean): indicates freemail addresses (Gmail, Yahoo, Outlook/Hotmail/Live, AOL, ...) [true | false] - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval - category, status_description: added from the numeric status code (category is VALID, SUSPECT, INVALID, INDETERMINATE or UNKNOWN)
validate_phoneRead-onlyValidate a phone number and return its status, line type, carrier codes, location and national/international formats. Result fields: - status (string): VALID_CONFIRMED, VALID_UNCONFIRMED, INVALID, DELAYED, RATE_LIMIT_EXCEEDED, API_KEY_INVALID_OR_DEPLETED - linetype (string): FIXED_LINE, MOBILE, VOIP, TOLL_FREE, PREMIUM_RATE, SHARED_COST, PERSONAL_NUMBER, PAGER, UAN, VOICEMAIL - location (string): geographical location (city, county, state) - countrycode (string): two letter ISO 3166-1 country code - formatnational (string): phone number in national format - formatinternational (string): phone number in international format - mcc (string): mobile country code to identify a mobile network operator (carrier) using the GSM (including GSM-R), UMTS, and LTE networks - mnc (string): mobile network code to identify a mobile network operator (carrier) using the GSM (including GSM-R), UMTS, and LTE networks - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval
validate_addressRead-onlyValidate and standardize a postal address and return its status, standardized address components, and optionally its coordinates. Result fields: - status (string): VALID: address is correct and deliverable. SUSPECT: address is incorrect and needs corrections to be deliverable, a suggested correction is provided. 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 a lot of different matches. In these cases automatic correction suggestions are not available. DELAYED, NO_COUNTRY, RATE_LIMIT_EXCEEDED, API_KEY_INVALID_OR_DEPLETED, RESTRICTED, INTERNAL_ERROR - formattedaddress (string): full address in standardized format - supplement (string): additional address details (building / unit / apt / suite etc.) - street (string): street address in standardized format - streetnumber (string): street number in standardized format - postalcode (string): zip / postal code in standardized format - city (string): city in standardized format - type (string): address type: S = Street address | P = P.O. Box, Pick-Up or other delivery service - rdi (string): Residential Delivery Indicator (Commercial / Residential) - district (string): district in standardized format - county (string): county in standardized format - state (string): state / province in standardized format - country (string): two-letter ISO 3166-1 country code - latitude (number): latitude (for valid addresses if Geocoding is enabled) - longitude (number): longitude (for valid addresses if Geocoding is enabled) - diagnostics (string): detailed diagnostic hints, indicating errors in the address input - corrections (string): detailed correction hints, indicating which parts of the address input have been fixed - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval
| validate_email | Validate an email address and return info about it. Result fields: - status (int): API result code. 401, 118 and 119 status codes indicate API errors: 401 -> info: 'Email address missing' 118 -> info: 'Rate Limit Exceeded' 119 -> info: 'API Key Invalid or Depleted' - info (string): short status description - details (string): full status description - freemail (boolean): indicates freemail addresses (Gmail, Yahoo, Outlook/Hotmail/Live, AOL, ...) [true | false] - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval - category, status_description: added from the numeric status code (category is VALID, SUSPECT, INVALID, INDETERMINATE or UNKNOWN) | Read-only |
| validate_phone | Validate a phone number and return its status, line type, carrier codes, location and national/international formats. Result fields: - status (string): VALID_CONFIRMED, VALID_UNCONFIRMED, INVALID, DELAYED, RATE_LIMIT_EXCEEDED, API_KEY_INVALID_OR_DEPLETED - linetype (string): FIXED_LINE, MOBILE, VOIP, TOLL_FREE, PREMIUM_RATE, SHARED_COST, PERSONAL_NUMBER, PAGER, UAN, VOICEMAIL - location (string): geographical location (city, county, state) - countrycode (string): two letter ISO 3166-1 country code - formatnational (string): phone number in national format - formatinternational (string): phone number in international format - mcc (string): mobile country code to identify a mobile network operator (carrier) using the GSM (including GSM-R), UMTS, and LTE networks - mnc (string): mobile network code to identify a mobile network operator (carrier) using the GSM (including GSM-R), UMTS, and LTE networks - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval | Read-only |
| validate_address | Validate and standardize a postal address and return its status, standardized address components, and optionally its coordinates. Result fields: - status (string): VALID: address is correct and deliverable. SUSPECT: address is incorrect and needs corrections to be deliverable, a suggested correction is provided. 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 a lot of different matches. In these cases automatic correction suggestions are not available. DELAYED, NO_COUNTRY, RATE_LIMIT_EXCEEDED, API_KEY_INVALID_OR_DEPLETED, RESTRICTED, INTERNAL_ERROR - formattedaddress (string): full address in standardized format - supplement (string): additional address details (building / unit / apt / suite etc.) - street (string): street address in standardized format - streetnumber (string): street number in standardized format - postalcode (string): zip / postal code in standardized format - city (string): city in standardized format - type (string): address type: S = Street address | P = P.O. Box, Pick-Up or other delivery service - rdi (string): Residential Delivery Indicator (Commercial / Residential) - district (string): district in standardized format - county (string): county in standardized format - state (string): state / province in standardized format - country (string): two-letter ISO 3166-1 country code - latitude (number): latitude (for valid addresses if Geocoding is enabled) - longitude (number): longitude (for valid addresses if Geocoding is enabled) - diagnostics (string): detailed diagnostic hints, indicating errors in the address input - corrections (string): detailed correction hints, indicating which parts of the address input have been fixed - ratelimit_remain (int): number of API requests remaining before the API rate limit is reached (the default API rate limit allows 100 API requests in 300s) - ratelimit_seconds (int): number of seconds remaining in the current rate limit interval | Read-only |
Configuration
AV_TOKENSecretAddress Validator API Token
EV_TOKENSecretEmail Validator API Token
PV_TOKENSecretPhone Validator API Token
| Name | Description | |
|---|---|---|
| AV_TOKEN | Address Validator API Token | Secret |
| EV_TOKEN | Email Validator API Token | Secret |
| PV_TOKEN | Phone Validator API Token | Secret |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablebyteplant-devops/byteplant-mcp is public and reachablegithub.com/byteplant-devops/byteplant-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-21github.com/byteplant-devops/byteplant-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from byteplant-mcpPass
- No critical advisory in the package or its dependencies33 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThis 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
-
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
- macOS:
-
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>" } } } } -
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 support@byteplant.com 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: contact@byteplant.com
License
Byteplant MCP questions
How do I add Byteplant MCP to Claude Code?
Run claude mcp add --env 'AV_TOKEN=<YOUR_AV_TOKEN>' --env 'EV_TOKEN=<YOUR_EV_TOKEN>' --env 'PV_TOKEN=<YOUR_PV_TOKEN>' byteplant-mcp -- uvx byteplant-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Byteplant MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Byteplant MCP provide?
It exposes 3 tools, including validate_email, validate_phone, validate_address.
Does it support international addresses?
Yes, it provides validation services in over 240 countries worldwide.
Can I use this with Claude on the web?
No, ChatGPT and Claude on the web or mobile only connect to remote MCP servers and cannot use this local server.
How do I provide my API keys?
You provide API keys as environment variables: EV_TOKEN for email, PV_TOKEN for phone, and AV_TOKEN for address.