MailProbe MCP server

mailprobe-mcp

Official Model Context Protocol server of the MailProbe API. Your AI assistant checks whether email addresses exist and can receive mail, in real time and without sending anything: one address, or a list before a campaign. Verification runs on OVHcloud servers in France, and the API stores no address.

Installation · Tools · How it behaves · Development

There are two ways to reach it, with the same two tools:

• the remote server that MailProbe runs at https://mailprobe.dev/mcp, for a client that connects to a remote server and can send a header: nothing to install;
• the local server of this package, npx -y mailprobe-mcp, for a client that starts its servers on your computer.

This repository also holds the Claude Code plugin and the skill that tells an assistant how to read a result and how to go through a list.

Installation

1. Create an account on mailprobe.dev. It comes with 100 free credits; see pricing for more.
2. Create an API key, which starts with mp_live_, under Developer in your account. MailProbe shows it only once, at creation.
3. Add one of the two servers to your MCP client.

Remote server

The key goes in the Authorization header. In Claude Code:

claude mcp add --transport http mailprobe https://mailprobe.dev/mcp --header "Authorization: Bearer mp_live_..."

In Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "mailprobe": {
      "url": "https://mailprobe.dev/mcp",
      "headers": { "Authorization": "Bearer mp_live_..." }
    }
  }
}

Any other client that connects to a remote MCP server and can send a header works the same way.

Local server

The key goes in the MAILPROBE_API_KEY environment variable, and the server needs Node.js 22 or later. In Claude Desktop and the other clients configured with a JSON file:

{
  "mcpServers": {
    "mailprobe": {
      "command": "npx",
      "args": ["-y", "mailprobe-mcp"],
      "env": { "MAILPROBE_API_KEY": "mp_live_..." }
    }
  }
}

The Claude and ChatGPT apps connect to a remote server only through an OAuth sign-in, which MailProbe does not offer yet. Claude Desktop takes the local server above; elsewhere, MailProbe is available through Zapier MCP.

Claude Code plugin

The plugin connects Claude Code to the remote server and adds a skill that tells the assistant how to read a result, what a call costs, and how to go through a list.

/plugin marketplace add mailprobe/mcp
/plugin install mailprobe@mailprobe

Claude Code asks for the API key when the plugin is enabled, and keeps it in the credential store of the system, not in a settings file. To set it later, run /plugin configure mailprobe@mailprobe, or open /plugin, Installed tab, mailprobe, Configure options. A remote server you added by hand at the same address takes precedence over the one of the plugin.

For another agent that loads SKILL.md skills, add one of the two servers above and take the skill alone: plugin/skills/mailprobe/SKILL.md in this repository, also listed on Agensi.

Then ask for what you need: "does jane@example.com exist?", "check the addresses of contacts.csv before I send the newsletter", "which of these sign-ups are disposable?".

Tools

Tool	What it does
verify_emails	Verifies 1 to 20 addresses and returns one result per address, in the order given: status (valid, invalid, risky or unknown), a score from 0 to 100, the reason of a verdict that is not plainly deliverable, the disposable, role_based, free_provider and catch_all flags, and did_you_mean for a likely typo
get_credits	Returns the credits left on the account of the API key

The fields of a result are those of the API: see the API documentation.

How it behaves

• Nothing is sent to the address. MailProbe checks the syntax, the mail servers of the domain, then asks the mail server whether the mailbox exists, and stops there.
• Nothing is stored. An address verified through the API is processed in memory and gone when the response is sent. No result is reused for a later request.
• The same tools on both servers. The local server carries the instructions and the tool definitions of the remote one, word for word, and words a refusal the same way. It adds nothing between the assistant and the API: it sends the addresses to https://mailprobe.dev/api/v1 and returns the answer.
• Credits. One credit per address actually probed, taken from your account as with the API. An address repeated in the same call, an entry that is not a well-formed address, an address that has no verdict yet when the call answers and one whose server refused the connection cost nothing. get_credits is free.
• Rate limit. The API accepts 60 calls per minute for an API key, and a call of 20 addresses counts as one. A refused call gives the number of seconds to wait. The local server waits by itself and tries again, twice at most, only for delays of 30 seconds or less and only while the call can still answer in time; otherwise the assistant gets the delay to wait.
• Response time. A call answers within about 55 seconds, on both servers, because MCP clients give up on a tool call after a minute. An address that has no verdict yet at that point comes back unknown with the reason timeout, at no charge: send it again.
• Long lists. A call takes 20 addresses, so an assistant sends a list in several calls. Above a few hundred addresses, the batch screen of your account is the right tool: a pasted list of up to 500 addresses, or a CSV or TXT file of up to 250,000, verified in the background.
• Errors. A refusal comes back to the assistant as a sentence it can act on: the key to set, the credits to buy, the delay to wait.
• Without a key. The local server starts and lists its tools; a call explains how to set MAILPROBE_API_KEY.

Every request of the local server carries User-Agent: mailprobe-mcp/<version>. Mention it when you contact support: it tells your calls apart in the API's logs.

Development

The local server has no dependency: Node.js runs the sources as they are. It talks to its client over stdio and serves both eras of the protocol from the same process: revision 2026-07-28, where each request carries its protocol version, and the earlier revisions (2025-11-25 down to 2024-11-05), which start with an initialize handshake.

npm test

runs the tests against a fake MailProbe API on a local port: no key and no network are needed. They also check that the package, the plugin, the skill and this README agree.

npm run check-tools

compares the instructions and the tool definitions of this package with those of the remote server, which gives them without a key.

Plugin

plugin/ holds the Claude Code plugin: its manifest, the .mcp.json that points at the remote server, and the skill, plugin/skills/mailprobe/SKILL.md. .claude-plugin/marketplace.json is the catalog that lets Claude Code install the plugin from this repository. Neither is part of the npm package.

claude plugin validate . --strict
claude --plugin-dir ./plugin

check the manifests, then start a session with the plugin loaded from the folder, without installing it. A user gets a change of the plugin or of the skill when the version changes: it ships with a release.

Releasing

1. Set the version in package.json and plugin/.claude-plugin/plugin.json, and date its section in CHANGELOG.md.
2. Run npm test and npm run check-tools.
3. Commit, then push a tag named after the version: the Publish workflow publishes the package to npm through Trusted Publishing, with a provenance statement.
4. When the skill changed, upload it again to its Agensi listing, as a new version: a ZIP of a mailprobe/ folder that holds the SKILL.md. Nothing updates the listing from this repository.

Resources

• MailProbe API documentation
• MCP setup on mailprobe.dev
• MailProbe skill on Agensi
• Model Context Protocol specification

Support

Open an issue or write to contact@mailprobe.dev.

License

MIT, see LICENSE.