Allows AI agents to create permanent email inboxes, read one-time passwords, and send emails.
Also known as MailFlat/mailflat-sdks, mailflat-sdks, mailflat-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 236
- Latest version
- 0.9.2
- Last commit
- Nov 13, 2026
- License
- MIT
What is MailFlat MCP?
MailFlat allows AI agents to create permanent email inboxes, read one-time passwords, and send emails.
Summary generated from the project's README
About MailFlat MCP server
MailFlat provides a way for AI agents and automated test suites to manage permanent email inboxes. Developers can use this service to create addresses that persist across multiple runs, which is useful for testing registration flows or managing agent communications. Unlike temporary email services, these addresses remain active while you control the message retention window.
Users connect to the service using an account key starting with mf_live_ obtained from the MailFlat dashboard. The mailflat-mcp package allows AI assistants like Claude or Cursor to interact with these inboxes directly. The system supports specific tasks such as creating new inboxes with custom labels, reading one-time passwords through specialized retrieval tools, and sending emails. This setup works for both local development and remote agent environments through various SDKs for Python, JavaScript, and Java.
What you can do with it
- 1Automated OTP retrievalAn AI agent can wait for and extract a verification code from an inbox to complete a signup process.
Written from the project's README. Every use case is checked against a quote from it.
How to install MailFlat MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MailFlat MCP in Claude Code
$ claude mcp add --env 'MAILFLAT_API_KEY=<YOUR_MAILFLAT_API_KEY>' mailflat-sdks -- uvx mailflat-mcpInstall MailFlat MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mailflat-sdks": {
"command": "uvx",
"args": [
"mailflat-mcp"
],
"env": {
"MAILFLAT_API_KEY": "<YOUR_MAILFLAT_API_KEY>"
}
}
}
}Install MailFlat MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mailflat-sdks": {
"type": "stdio",
"command": "uvx",
"args": [
"mailflat-mcp"
],
"env": {
"MAILFLAT_API_KEY": "<YOUR_MAILFLAT_API_KEY>"
}
}
}
}Install MailFlat MCP in VS Code CLI
$ code --add-mcp '{"name":"mailflat-sdks","type":"stdio","command":"uvx","args":["mailflat-mcp"],"env":{"MAILFLAT_API_KEY":"<YOUR_MAILFLAT_API_KEY>"}}'Install MailFlat MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mailflat-sdks": {
"command": "uvx",
"args": [
"mailflat-mcp"
],
"env": {
"MAILFLAT_API_KEY": "<YOUR_MAILFLAT_API_KEY>"
}
}
}
}Install MailFlat MCP in Codex
$ codex mcp add mailflat-sdks --env 'MAILFLAT_API_KEY=<YOUR_MAILFLAT_API_KEY>' -- uvx mailflat-mcpInstall MailFlat MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mailflat-sdks] command = "uvx" args = ["mailflat-mcp"] [mcp_servers.mailflat-sdks.env] MAILFLAT_API_KEY = "<YOUR_MAILFLAT_API_KEY>"
Install MailFlat MCP in Gemini CLI
$ gemini mcp add -s user -e 'MAILFLAT_API_KEY=<YOUR_MAILFLAT_API_KEY>' mailflat-sdks uvx -- mailflat-mcpInstall MailFlat MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mailflat-sdks": {
"command": "uvx",
"args": [
"mailflat-mcp"
],
"env": {
"MAILFLAT_API_KEY": "<YOUR_MAILFLAT_API_KEY>"
}
}
}
}Configuration
MAILFLAT_API_KEYRequiredSecretMailFlat API key. Create one in the dashboard under Agents.
MAILFLAT_API_URLOverride the API base URL. Defaults to https://mailflat.net.
| Name | Description | |
|---|---|---|
| MAILFLAT_API_KEY | MailFlat API key. Create one in the dashboard under Agents. | RequiredSecret |
| MAILFLAT_API_URL | Override the API base URL. Defaults to https://mailflat.net. |
Automated checks
Ran Nov 14, 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 reachablemailflat/mailflat-sdks is public and reachablegithub.com/mailflat/mailflat-sdks ↗Pass
- Package names this repository as its sourcemailflat-mcp names mailflat/mailflat-sdks as sourcepypi.org/project/mailflat-mcp/ ↗Pass
- 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-11-13github.com/mailflat/mailflat-sdks ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mailflat-mcpPass
- No critical advisory in the package or its dependencies31 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMailFlat SDKs
Official client libraries for MailFlat: email inboxes your code owns, with one-line OTP retrieval. Built for test suites (Selenium, pytest, Playwright) and AI agents.
Addresses are permanent, so a suite does not need a fresh one per run. Only the messages expire, on a retention window you choose.
This repo holds only the open-source SDKs. The MailFlat service itself is closed-source.
Packages
| Package | For | Install |
|---|---|---|
mailflat |
Python | pip install mailflat |
@mailflat/sdk |
JavaScript / TypeScript | npm i @mailflat/sdk |
mailflat-mcp |
AI assistants (Claude, Cursor) — MCP | uvx mailflat-mcp |
@mailflat/ai-sdk |
Vercel AI SDK agents | npm i @mailflat/ai-sdk |
mailflat.langchain |
LangChain agents | pip install "mailflat[langchain]" |
mailflat-sdk (Java) |
Java / Selenium | via JitPack — see below |
Each client is a thin, typed wrapper over the same /api/v1 Agent API, so they behave identically.
Authenticate with your account key (mf_live_…) from the dashboard (Agents → API keys).
Java / Selenium (JitPack)
JitPack derives the
groupIdfrom the GitHub owner. This repo moved to the officialMailFlataccount in August 2026, so releases fromv0.4.4on publish ascom.github.MailFlat:mailflat-sdks. Earlier versions still resolve under the old coordinatecom.github.onderyentar21:mailflat-sdks; the old repo stays up for them. The client is moving to Maven Central (net.mailflat) next, which ends the owner coupling.
<repositories>
<repository><id>jitpack.io</id><url>https://jitpack.io</url></repository>
</repositories>
<dependency>
<groupId>com.github.MailFlat</groupId>
<artifactId>mailflat-sdks</artifactId>
<version>v0.8.1</version>
</dependency>
MailFlat mf = new MailFlat("mf_live_…");
Inbox inbox = mf.create("signup");
driver.findElement(By.id("email")).sendKeys(inbox.address());
String otp = inbox.waitForOtp(30); // polls until the code arrives
driver.findElement(By.id("code")).sendKeys(otp);
Quick examples
Python
from mailflat import MailFlat
mf = MailFlat(api_key="mf_live_…")
inbox = mf.create(label="signup")
otp = inbox.wait_for_otp(timeout=30)
JavaScript / TypeScript
import { MailFlat } from "@mailflat/sdk";
const mf = new MailFlat({ apiKey: process.env.MAILFLAT_API_KEY });
const inbox = await mf.create({ label: "signup" });
const otp = await inbox.waitForOtp({ timeout: 30000 });
License
MIT. The full text is in LICENSE at the repository root; each package directory carries an identical copy.
MailFlat MCP questions
How do I add MailFlat MCP to Claude Code?
Run claude mcp add --env 'MAILFLAT_API_KEY=<YOUR_MAILFLAT_API_KEY>' mailflat-sdks -- uvx mailflat-mcp in your terminal. Add --scope user to make it available in every project.
How do I add MailFlat MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I authenticate with MailFlat?
You authenticate using an account key (starting with mf_live_...) obtained from the dashboard under Agents → API keys.
Are the email addresses temporary?
No, the addresses are permanent, though messages expire based on a retention window you select.
What programming languages are supported?
MailFlat provides SDKs for Python, JavaScript/TypeScript, Java, and integrations for LangChain and Vercel AI SDK.