mailpit_mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mailpit_mcpget latest email for user@example.test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mailpit_mcp
Model Context Protocol (MCP) server and HTTP client for Mailpit — local SMTP capture and inbox inspection for development and E2E testing.
Connects to a Mailpit instance on your machine (default http://127.0.0.1:8025). No cloud services, no stored credentials in this repository.
Requirements
Node.js 20+
A running Mailpit instance (Docker or binary)
Related MCP server: mailpit-mcp-server
Install
git clone https://github.com/exabyteso/mailpit_mcp.git
cd mailpit_mcp
npm installEnvironment
Copy .env.example to .env locally (.env is gitignored). All configuration is optional:
Variable | Default | Description |
|
| Mailpit HTTP API base URL |
| — | Basic auth username (if enabled on Mailpit) |
| — | Basic auth password |
|
| HTTP request timeout |
Run the MCP server
npm startCursor / MCP client registration
Add to your workspace .cursor/mcp.json:
{
"mcpServers": {
"mailpit-local": {
"command": "node",
"args": ["src/index.mjs"],
"cwd": "/absolute/path/to/mailpit_mcp",
"env": {
"MAILPIT_URL": "http://127.0.0.1:8025"
}
}
}
}When mailpit_mcp is cloned next to another project (sibling under Projects/), you can use a relative cwd from that project's workspace root.
MCP tools
Tool | Description |
|
|
| Recent messages |
| Mailpit search query |
| Full message by ID |
| Latest mail to an address |
| Poll until a message matches |
| Parse verification code from body |
| Clear mailbox (test reset) |
Programmatic client
import { createMailpitClient, extractOtp } from 'mailpit-mcp/client';
const mailpit = createMailpitClient();
await mailpit.deleteAll();
const message = await mailpit.waitForMessage({
to: 'user@example.test',
timeoutMs: 10_000,
});
const code = extractOtp(message.Text ?? '');Tests
npm testUnit tests use fixtures only — no live Mailpit required.
Security
See SECURITY.md. This repo ships no secrets. Configure auth via environment variables on your machine only.
License
MIT — see LICENSE.
Available Tools
8 toolsmailpit_delete_allADestructive
Delete all messages in the Mailpit mailbox (test reset)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true. The description adds 'Delete all messages' and 'test reset' context, but does not detail irreversibility or side effects beyond what annotations suggest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 6 words, front-loads the action, and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 0 parameters and no output schema, the description fully covers the purpose and context. The 'test reset' phrase adds important usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist. Per guidelines, 0 parameters gives baseline 4. Description adds no param info as none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete all messages' and the resource 'Mailpit mailbox', with purpose 'test reset'. It distinguishes from sibling tools like mailpit_get_message and mailpit_list_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for testing resets but does not explicitly state when to use vs alternatives or when not to use. However, the sibling context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_extract_otpARead-only
Extract a numeric verification code from message plain text or HTML
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Raw text to parse | |
| message_id | No | Fetch body from this message ID instead |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds little beyond that. It does not disclose behavior when both parameters are provided or what happens if no code is found. With annotations covering safety, the description provides minimal extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any wasteful words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity (two optional parameters, no output schema), but the description omits details like return format or error handling. It is adequate but leaves gaps for an agent to guess behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no new meaning beyond the parameter names and schema descriptions. The baseline of 3 is appropriate as the schema already documents the purpose of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts a numeric verification code from message plain text or HTML. It uses a specific verb and resource, and it distinguishes itself from sibling tools like mailpit_get_message and mailpit_search, which handle full messages or searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as mailpit_get_message for full message retrieval. It does not mention exclusions or preferred contexts, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_get_latest_for_recipientBRead-only
Get the most recent message sent to a recipient email address
| Name | Required | Description | Default |
|---|---|---|---|
| recipient | Yes | Recipient email address |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, which is consistent. The description adds minimal additional context beyond the purpose. It does not disclose behavior like what happens if no message is found or if multiple messages exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the main purpose. However, it could mention edge cases like no messages found or the ordering logic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'recipient', which has a clear description and email format. The description does not add extra semantics beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'the most recent message sent to a recipient email address'. It distinguishes from siblings like mailpit_list_messages which lists multiple messages, and mailpit_wait_for_message which waits for a message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as mailpit_list_messages or mailpit_search. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_get_messageARead-only
Get full message content by ID (or "latest")
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message ID or "latest" |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only. The description adds the 'latest' special value but does not disclose error behavior, return format, or any other side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and includes the key special value in parentheses, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description provides the essential purpose and special value. It lacks a mention of what constitutes 'full message content' but is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the parameter with a clear description. The tool description merely repeats 'by ID (or "latest")' without adding new semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full message content') and distinguishes itself from siblings like 'mailpit_get_latest_for_recipient' by emphasizing lookup by arbitrary ID or the special value 'latest'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific message ID or want the latest message, but it does not explicitly state when to use this tool versus alternatives like 'mailpit_list_messages' or 'mailpit_get_latest_for_recipient'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_healthARead-only
Check Mailpit server health via GET /api/v1/info
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only. Description adds the specific endpoint, but does not disclose what the response contains or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently conveys the tool's purpose with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, read-only annotation, and simple purpose, the description is largely complete. However, lacking output schema details slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Baseline of 4 applies; description adds nothing about parameters but is not needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Check' and resource 'Mailpit server health', and specifies the API endpoint. Distinct from sibling tools which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage as a health check, but no explicit guidance on when to use this tool over alternatives, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_list_messagesBRead-only
List recent captured messages (newest first)
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Pagination offset | |
| limit | No | Max messages to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only. Description adds ordering behavior (newest first) but lacks further context like pagination behavior beyond schema, or what constitutes 'recent'. For a read-only list, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single phrase with no wasted words. Front-loads key action and ordering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so tool fails to describe return format or fields. While read-only with simple params, agents may need to know what fields are in each message to decide if this list suffices versus using get_message. Missing this context reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with descriptions for both parameters (pagination offset, max messages). Description does not add semantic details beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (list) and resource (captured messages), and specifies ordering (newest first). It distinguishes from siblings like mailpit_search (searching) and mailpit_get_message (single message) but does not explicitly contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. Siblings include search and get_message, but description does not clarify that this is for unfiltered recent list, while others are for filtering or single retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_searchARead-only
Search messages using Mailpit query syntax (e.g. to:user@example.test subject:welcome)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Mailpit search query | |
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by specifying the Mailpit query syntax, which is beyond the annotations and helps the agent understand how to construct searches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no unnecessary words. It front-loads the purpose and provides a useful example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, yet the description does not mention what the search returns (e.g., message IDs or full details). Also missing details on pagination, ordering, or result limits beyond the limit parameter. For a search tool among 7 siblings, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only query has a description). The description provides a concrete example for the query parameter, adding meaningful context. The limit parameter is not elaborated beyond the schema, but the example partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and the resource 'messages', with an explicit example of the query syntax (e.g., to:user@example.test subject:welcome). It distinguishes from sibling tools like mailpit_list_messages and mailpit_get_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives (e.g., mailpit_list_messages). The example implies usage for searching, but context for selection is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mailpit_wait_for_messageBRead-only
Poll Mailpit until a matching message arrives or timeout
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| subject_contains | No | ||
| query | No | ||
| timeout_ms | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds that the tool polls and has a timeout, which is adequate but doesn't detail polling frequency or behavior on timeout.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no waste; concise but could benefit from brief parameter explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output schema, no parameter descriptions, and lacks details on return value, behavior on timeout, or how filters combine, making it incomplete for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only mentions 'matching message' without elaborating on the filter parameters (to, from, subject_contains, query) or the timeout parameter beyond the schema's type and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls Mailpit for a matching message with a timeout, distinguishing it from sibling tools like mailpit_search which searches existing messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like mailpit_search or mailpit_list_messages; the description implies waiting for new messages but doesn't contrast with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
8 tool updates
v0.1.0- First observed
mailpit_delete_all - First observed
mailpit_extract_otp - First observed
mailpit_get_latest_for_recipient - First observed
mailpit_get_message - First observed
mailpit_health - First observed
mailpit_list_messages - First observed
mailpit_search - First observed
mailpit_wait_for_message
TDQS
Each tool has a clearly distinct purpose: delete all, extract OTP, get latest for recipient, get by ID, health check, list, search, and wait. No overlap or ambiguity.
All tools start with 'mailpit_' and most follow a verb_noun pattern (e.g., mailpit_delete_all, mailpit_list_messages). However, 'mailpit_health' is a noun only and 'mailpit_search' is a verb without a noun, causing slight inconsistency.
8 tools is well-scoped for an email testing server. Each tool serves a necessary function without being excessive or insufficient.
The tool set covers all essential operations for Mailpit: health check, listing, retrieving, searching, waiting, extracting OTPs, and resetting the mailbox. No obvious gaps for the intended domain.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Disposable test mailboxes on a real domain: send, receive and assert on real email.
Test-inbox API for email and SMS: create inboxes, long-poll messages, extract OTPs and links.
MCP server for e-mail testing: create disposable inboxes, wait for delivery, and extract e-mail content or links - all from your AI agent or test automation workflow. Get a free API key on https://app.zyntra.app/
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Mailosaur email and SMS testing services, allowing message management, server configuration, file downloads, spam analysis, and TOTP code retrieval via natural language.29MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, and manage emails from Mailpit, an email and SMTP testing tool, during development and testing.MIT
- FlicenseAqualityBmaintenanceProvides a dummy SMTP server for catching emails during development, with MCP tools to list, retrieve, and manage received messages.4-
- AlicenseNot gradedqualityCmaintenanceProvides MCP tools to manage MailDev Docker containers and inspect received emails, including listing, searching, retrieving, deleting, waiting for, and verifying email content and attachments for local development and test automation.2MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/exabyteso/mailpit_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server