Skip to main content
Glama
exabyteso

mailpit_mcp

by exabyteso

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 install

Environment

Copy .env.example to .env locally (.env is gitignored). All configuration is optional:

Variable

Default

Description

MAILPIT_URL

http://127.0.0.1:8025

Mailpit HTTP API base URL

MAILPIT_AUTH_USER

Basic auth username (if enabled on Mailpit)

MAILPIT_AUTH_PASS

Basic auth password

MAILPIT_TIMEOUT_MS

30000

HTTP request timeout

Run the MCP server

npm start

Cursor / 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

mailpit_health

GET /api/v1/info

mailpit_list_messages

Recent messages

mailpit_search

Mailpit search query

mailpit_get_message

Full message by ID

mailpit_get_latest_for_recipient

Latest mail to an address

mailpit_wait_for_message

Poll until a message matches

mailpit_extract_otp

Parse verification code from body

mailpit_delete_all

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 test

Unit 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 tools
mailpit_delete_allA
Destructive

Delete all messages in the Mailpit mailbox (test reset)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_otpA
Read-only

Extract a numeric verification code from message plain text or HTML

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoRaw text to parse
message_idNoFetch body from this message ID instead

TDQS

A3.5/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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_recipientB
Read-only

Get the most recent message sent to a recipient email address

ParametersJSON Schema
NameRequiredDescriptionDefault
recipientYesRecipient email address

TDQS

B3.4/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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_messageA
Read-only

Get full message content by ID (or "latest")

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesMessage ID or "latest"

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_healthA
Read-only

Check Mailpit server health via GET /api/v1/info

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_messagesB
Read-only

List recent captured messages (newest first)

ParametersJSON Schema
NameRequiredDescriptionDefault
startNoPagination offset
limitNoMax messages to return

TDQS

B3.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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_wait_for_messageB
Read-only

Poll Mailpit until a matching message arrives or timeout

ParametersJSON Schema
NameRequiredDescriptionDefault
toNo
fromNo
subject_containsNo
queryNo
timeout_msNo

TDQS

B3.2/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

  1. 8 tool updatesv0.1.0
    • First observedmailpit_delete_all
    • First observedmailpit_extract_otp
    • First observedmailpit_get_latest_for_recipient
    • First observedmailpit_get_message
    • First observedmailpit_health
    • First observedmailpit_list_messages
    • First observedmailpit_search
    • First observedmailpit_wait_for_message

TDQS

A3.8/5.0
Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

8 tools is well-scoped for an email testing server. Each tool serves a necessary function without being excessive or insufficient.

Completeness5/5

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

ActivityStale
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Enables interaction with Mailosaur email and SMS testing services, allowing message management, server configuration, file downloads, spam analysis, and TOTP code retrieval via natural language.
    29
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides 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.
    2
    MIT

Latest Blog Posts

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