MCP Server - Mailcatcher Docs

Mailcatcher exposes an MCP (Model Context Protocol) server, allowing AI assistants such as Claude Desktop and Cursor to read and inspect your test emails directly — no browser required.

What is MCP?

MCP is an open standard that lets AI assistants connect to external tools and data sources. Once your AI client is configured, you can ask it natural-language questions like:

"Show me the latest password-reset email in my staging project."
"List all emails received in the last hour."
"What does the welcome email HTML look like?"

The AI assistant calls the Mailcatcher MCP tools behind the scenes and returns the results inline in the conversation.

Access to the MCP server is secured with a personal API token. Each token is tied to your user account and gives exactly the same data access as your regular web session — scoped to your organisation.

Generate a token

Go to your Profile page
Find the MCP API Token card
Click Generate token
Copy the token immediately — it is only shown once

Store your token in a safe place. Once you navigate away, you cannot retrieve it again — you can only revoke it and generate a new one.

Revoke a token

Click Revoke on the MCP API Token card to invalidate the current token immediately. Any AI client using the old token will lose access instantly.

Available Tools

The MCP server exposes four tools to connected AI assistants:

`whoami`

Returns basic information about the authenticated user.

Field	Description
`name`	Your display name
`email`	Your email address
`organization`	Your organisation name

`list-projects`

Lists all projects (inboxes) your account has access to.

Field	Description
`id`	Project UUID
`name`	Project display name
`slug`	URL-friendly identifier
`storage-usage`	Disk usage in bytes
`amount-emails`	Total number of emails stored

`list-emails`

Lists emails in a project with pagination.

Inputs:

Parameter	Type	Default	Description
`projectId`	UUID	—	The project to list emails from
`page`	integer	`1`	Page number
`itemsPerPage`	integer	`10`	Items per page (max `50`)

Output: A paginated list of emails (each with id, from, to, subject) plus pagination metadata (page, items-per-page, total-items).

`show-email`

Returns the full content of a single email.

Input: emailId (UUID)

Output:

Field	Description
`html`	HTML body (nullable)
`text`	Plain-text body (nullable)
`header`	All raw email headers
`appendices`	List of attachments (`charset`, `contentType`, `fileName`)

Access is denied if the requested email does not belong to a project in your organisation.

Next Steps

Ready to connect your AI assistant? See Connecting AI Tools for step-by-step setup instructions for Claude Desktop, Cursor, and other MCP clients.