io.github.richelo/isitdisposable-mcp
An MCP server that lets AI agents check whether an email address or domain is disposable.
Open source Open in the app JSON README (API)
About
An MCP server that lets AI agents check whether an email address or domain is disposable.
Details
- Kind
- MCP servers
- Topic
- Communication
- Publisher
- richelo
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-08-05T05:37:56Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:18
- Updated
- 2026-08-29 04:01:18
- Origin id
io.github.richelo/isitdisposable-mcp
README
# isitdisposable-mcp
A Model Context Protocol (MCP) server that lets an AI agent check whether an email address or domain is disposable, using the isitdisposable.com application programming interface (API).
## Installation
The server is published to the npm registry and is normally run with `npx`, so there is nothing to install by hand; the examples below show how to wire it into a Model Context Protocol (MCP) host.
### Claude Desktop
Add this to your Claude Desktop configuration:
```json
{
"mcpServers": {
"isitdisposable": {
"command": "npx",
"args": ["-y", "isitdisposable-mcp"],
"env": { "ISITDISPOSABLE_API_KEY": "your_secret_key" }
}
}
}
```
### Claude Code
```
claude mcp add isitdisposable --env ISITDISPOSABLE_API_KEY=your_secret_key -- npx -y isitdisposable-mcp
```
## Getting an API key
An isitdisposable.com key is required. Get a free key at https://isitdisposable.com (a free tier is available), then set it as `ISITDISPOSABLE_API_KEY` in the configuration above.
## Tools
| Tool | What it does |
| --- | --- |
| `check_email` | Checks a single email address to see whether it is disposable. |
| `check_domain` | Checks a single bare domain (no local part) to see whether it is disposable. |
| `check_batch` | Checks up to 100 email addresses or bare domains at once in a single call. Mix full addresses and bare domains freely in the `items` list; entries containing an `@` sign are sent as email addresses, everything else as a domain. |
Every tool returns the same verdict shape. `disposable` is the core true or false verdict: a disposable address is a throwaway or temporary inbox used to receive a single signup message and evade normal registration requirements, rather than a real, ongoing mailbox. `action` is the recommended handling of `allow`, `warn`, or `block`. A handful of opt in signals may also be present, including `mx_valid` (whether the domain's mail servers accept mail), `relay` (a forwarding or catch all style address), `public_domain` (a well known free provider such as Gmail), and `did_you_mean` (a likely intended domain when the one given looks like a typo).
## Fail open behavior
This server always fails open. If a network problem, a timeout, a rate limit, or a server error prevents a real check from completing, the tool call still succeeds (it never throws or crashes the connection). It retries once after a short delay, and if that also fails, it returns a result with `checked: false`, `disposable: null`, and `action: "allow"`, along with a `note` explaining that the check could not be completed. An agent using this tool should treat that outcome as inconclusive, not as a signal that the address is safe.
If no API key is configured, the server still starts normally and responds to the Model Context Protocol (MCP) handshake; each tool call then returns an error result pointing to https://isitdisposable.com to get a free key.