Metadata-Version: 2.5
Name: byteplant-mcp
Version: 1.1.0
Summary: Byteplant's Email Validator, Phone Validator and Address Validator MCP Server
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp<3,>=2.2
Requires-Dist: requests>=2.32.5
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.byteplant-devops/byteplant-mcp -->
<p align="center">
  <img src="https://www.byteplant.com/img/logo.png" alt="Byteplant" width="400">
</p>

<h1 align="center">Byteplant MCP Server</h1>

<p align="center">
  Validate email addresses, phone numbers and postal addresses from any <a href="https://modelcontextprotocol.io/">MCP</a> client,<br>
  with unparalleled precision in 240+ countries worldwide.
</p>

<p align="center">
  <a href="https://pypi.org/project/byteplant-mcp/"><img src="https://img.shields.io/pypi/v/byteplant-mcp" alt="PyPI version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> ·
  <a href="#tools">Tools</a> ·
  <a href="#credentials">Credentials</a> ·
  <a href="#usage">Usage</a> ·
  <a href="#compatibility">Compatibility</a> ·
  <a href="#resources">Resources</a>
</p>

---

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](https://docs.astral.sh/uv/getting-started/installation/). `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](#credentials). 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:

   ```json
   {
     "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

```bash
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](#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:

```json
{
  "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

```bash
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):

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

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

```json
"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](https://www.byteplant.com/email-validator/api.html) |
| `PV_TOKEN` | `validate_phone` | [Phone Validator](https://www.byteplant.com/phone-validator/api.html) |
| `AV_TOKEN` | `validate_address` | [Address Validator](https://www.byteplant.com/address-validator/api.html) |

You can manage your keys in your [Byteplant account](https://www.byteplant.com/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](https://www.byteplant.com/email-validator/api.html)

| 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](https://www.byteplant.com/email-validator/validation-results.html). |
| `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](https://www.byteplant.com/email-validator/validation-results.html) |
| `details` | [Full status description](https://www.byteplant.com/email-validator/validation-results.html) |
| `freemail` | `true` if the address belongs to a freemail provider (Gmail, Yahoo, Outlook/Hotmail/Live, AOL, …) |

### `validate_phone` - [API Docs](https://www.byteplant.com/phone-validator/api.html)

| 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](https://www.byteplant.com/address-validator/api.html)

| 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](https://www.byteplant.com/address-validator/validation-diagnostic-hints.html). |
| `corrections` | Hints about which parts of the address input were fixed. See the [full list of correction hints](https://www.byteplant.com/address-validator/validation-diagnostic-hints.html). |
| `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](https://modelcontextprotocol.io/)
- [Email Validator API documentation](https://www.byteplant.com/email-validator/api.html)
- [Phone Validator API documentation](https://www.byteplant.com/phone-validator/api.html)
- [Address Validator API documentation](https://www.byteplant.com/address-validator/api.html)
- [Byteplant website](https://www.byteplant.com/)
- Contact: [contact@byteplant.com](mailto:contact@byteplant.com)

## License

[MIT](LICENSE)
