Merge pull request #375 from ChangemakerStudios/feature/mcp-server

Add MCP server support to Papercut.Service

Author: Jaben

README.md

@@ -33,14 +33,24 @@ docker run -d -p 8080:8080 -p 2525:2525 changemakerstudiosus/papercut-smtp:lates
 
 Web UI at **http://localhost:8080**, SMTP on **localhost:2525**. Details on [Docker Hub](https://hub.docker.com/r/changemakerstudiosus/papercut-smtp).
 
+## MCP Server (AI Agents)
+
+The Papercut Service includes an optional [Model Context Protocol](https://modelcontextprotocol.io/) server, so AI agents like Claude Code can inspect the email your app sends — list messages, assert on bodies and headers, verify attachment content, and clean up between test runs. Off by default; enable it with the `EnableMcpServer` setting, then connect:
+
+```bash
+claude mcp add --transport http papercut http://localhost:8080/mcp
+```
+
+See the [MCP Server documentation](https://www.papercut-smtp.com/mcp/) for setup and the full tool reference.
+
 ## Documentation
 
 **[www.papercut-smtp.com](https://www.papercut-smtp.com/)** — full documentation:
 
 - [How It Works](https://www.papercut-smtp.com/how-it-works/) — what Papercut is (and isn't), in two minutes
 - [Getting Started](https://www.papercut-smtp.com/getting-started/) — install, first run, first test email
 - [Send Email from Your App](https://www.papercut-smtp.com/send-from-your-app/) — copy-paste config for .NET, Node, Python, PHP, Java, Ruby
-- [Desktop App](https://www.papercut-smtp.com/desktop/) · [Service & Web UI](https://www.papercut-smtp.com/service/) · [Docker](https://www.papercut-smtp.com/docker/) · [TLS & Auth](https://www.papercut-smtp.com/smtp-tls-auth/)
+- [Desktop App](https://www.papercut-smtp.com/desktop/) · [Service & Web UI](https://www.papercut-smtp.com/service/) · [MCP Server](https://www.papercut-smtp.com/mcp/) · [Docker](https://www.papercut-smtp.com/docker/) · [TLS & Auth](https://www.papercut-smtp.com/smtp-tls-auth/)
 - [Troubleshooting](https://www.papercut-smtp.com/troubleshooting/)
 
 ## Release History

docs/mcp.md

@@ -0,0 +1,88 @@
+# MCP Server (AI Agents)
+
+The Papercut SMTP Service includes an optional **[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server** that lets AI agents and coding assistants — Claude Code, and any other MCP-capable client — inspect the email your application sends during development.
+
+A typical agent-driven test loop:
+
+1. The agent triggers your app to send an email
+2. `list_messages` — confirm it arrived
+3. `get_message` — assert on subject, recipients, and body
+4. `get_message_section` — verify an attachment's actual content
+5. `delete_all_messages` — reset for the next test
+
+!!! note "Off by default"
+    The MCP server is disabled unless you explicitly enable it. The service logs its status at startup either way:
+
+    ```
+    [INF] MCP server is enabled -- serving MCP endpoint at /mcp
+    [INF] MCP server is disabled (set EnableMcpServer to true to enable)
+    ```
+
+## Enabling
+
+Set `EnableMcpServer` to `true` using any of the service's [configuration layers](service.md#configuration):
+
+=== "appsettings.json"
+
+    ```json
+    { "EnableMcpServer": true }
+    ```
+
+=== "Environment variable"
+
+    ```powershell
+    $env:EnableMcpServer = 'true'
+    ```
+
+=== "Docker"
+
+    ```bash
+    docker run -d -p 8080:8080 -p 2525:2525 \
+      -e EnableMcpServer=true \
+      changemakerstudiosus/papercut-smtp:latest
+    ```
+
+Restart the service after changing it. When enabled, the endpoint is served at:
+
+```
+http://localhost:8080/mcp
+```
+
+(Streamable HTTP transport; the path respects `HttpPathPrefix` if configured.) The web UI shows an **MCP** badge in the navigation bar when the server is on — hover it for the endpoint URL, click to copy. The URL is also available programmatically at `GET /api/mcp`.
+
+## Connecting a client
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http papercut http://localhost:8080/mcp
+```
+
+**Generic MCP client configuration:**
+
+```json
+{
+  "mcpServers": {
+    "papercut": {
+      "type": "http",
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_messages` | Paged message summaries, newest first (`limit`, `start`) |
+| `get_message` | Full detail for one message: from/to/cc/bcc, subject, text and HTML bodies, headers, and a manifest of MIME sections (index, contentId, media type, filename, attachment flag, size) |
+| `get_message_section` | Decoded content of a single MIME part, selected by `index` or `contentId` from the manifest — text parts return as text, binary parts as base64 |
+| `get_message_raw` | The raw RFC 822 (`.eml`) source of a message |
+| `delete_message` | Delete one message by id |
+| `delete_all_messages` | Clear the message store |
+
+Large content is truncated to keep responses manageable (raw messages at 200K characters, binary sections at 512KB) with a `truncated` flag pointing to the full-content REST endpoints (`/api/messages/{id}/raw` and `/api/messages/{id}/sections/{index}`).
+
+!!! warning "Network exposure"
+    Like the REST API and web UI, the MCP endpoint has **no built-in authentication** — anyone who can reach the HTTP port can read and delete messages. Keep the binding on `localhost`, or put a reverse proxy with auth in front of it. See the [network exposure warning](service.md#configuration).

docs/service.md

@@ -68,3 +68,5 @@ Use `http://0.0.0.0:8080` to listen on all interfaces — but read the warning b
 ## API
 
 The web UI is backed by a small HTTP API (`/api/messages`, etc.) you can script against — handy for asserting "an email was sent" in end-to-end tests. Explore the endpoints via your browser's dev tools on the web UI.
+
+For AI agents and coding assistants, the service can also expose these operations over the Model Context Protocol — see [MCP Server](mcp.md).

mkdocs.yml

@@ -44,6 +44,7 @@ nav:
     - Send Email from Your App: send-from-your-app.md
     - Desktop App: desktop.md
     - Service & Web UI: service.md
+    - MCP Server (AI Agents): mcp.md
     - Docker: docker.md
     - TLS & Authentication: smtp-tls-auth.md
   - Troubleshooting: troubleshooting.md

src/Papercut.Service/Application/Controllers/McpController.cs

@@ -0,0 +1,48 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using Microsoft.Extensions.Configuration;
+
+using Papercut.Service.Application.Mcp;
+
+namespace Papercut.Service.Application.Controllers;
+
+[Route("api/[controller]")]
+public class McpController(ISettingStore settingStore, IConfiguration configuration) : ControllerBase
+{
+    [HttpGet]
+    public McpStatusDto Get()
+    {
+        var enabled = McpServerSettings.IsEnabled(settingStore, configuration);
+
+        return new McpStatusDto
+        {
+            Enabled = enabled,
+            Url = enabled
+                ? $"{this.Request.Scheme}://{this.Request.Host}{this.Request.PathBase}{McpServerSettings.EndpointPath}"
+                : null
+        };
+    }
+
+    public class McpStatusDto
+    {
+        public bool Enabled { get; set; }
+
+        public string? Url { get; set; }
+    }
+}

src/Papercut.Service/Application/Controllers/MessageNotFoundException.cs

@@ -0,0 +1,41 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using Microsoft.AspNetCore.Mvc.Filters;
+
+using ModelContextProtocol;
+
+namespace Papercut.Service.Application.Controllers;
+
+/// <summary>
+///     Derives from <see cref="McpException" /> so the same throw surfaces as a tool error
+///     over MCP and, via <see cref="MessageNotFoundExceptionFilterAttribute" />, a 404 over REST.
+/// </summary>
+public class MessageNotFoundException(string messageId) : McpException($"Message '{messageId}' was not found");
+
+public class MessageNotFoundExceptionFilterAttribute : ExceptionFilterAttribute
+{
+    public override void OnException(ExceptionContext context)
+    {
+        if (context.Exception is MessageNotFoundException)
+        {
+            context.Result = new NotFoundResult();
+            context.ExceptionHandled = true;
+        }
+    }
+}

src/Papercut.Service/Application/Controllers/MessagesController.cs

@@ -16,16 +16,28 @@
 // limitations under the License.
 
 
+using System.ComponentModel;
+
+using ModelContextProtocol;
+using ModelContextProtocol.Server;
+
 using Papercut.Service.Web;
 
 namespace Papercut.Service.Application.Controllers;
 
 [Route("api/[controller]")]
+[McpServerToolType]
+[MessageNotFoundExceptionFilter]
 public class MessagesController(IMessageRepository messageRepository, IMimeMessageLoader messageLoader, ILogger logger)
     : ControllerBase
 {
     [HttpGet]
-    public async Task<GetMessagesResponse> GetAll(int limit = 10, int start = 0, CancellationToken token = default)
+    [McpServerTool(Name = "list_messages")]
+    [Description("Lists received email messages, newest first. Returns the total message count and a page of message summaries (id, subject, size, created date).")]
+    public async Task<GetMessagesResponse> GetAll(
+        [Description("Maximum number of messages to return (default 10)")] int limit = 10,
+        [Description("Zero-based offset to start from, for paging (default 0)")] int start = 0,
+        CancellationToken token = default)
     {
         var messageEntries = messageRepository.LoadMessages().ToList();
 
@@ -43,29 +55,39 @@ public async Task<GetMessagesResponse> GetAll(int limit = 10, int start = 0, Can
     }
 
     [HttpDelete]
-    public void DeleteAll()
+    [McpServerTool(Name = "delete_all_messages")]
+    [Description("Deletes all received email messages.")]
+    public string DeleteAll()
     {
+        var deleted = 0;
+        var failed = 0;
+
         foreach (var msg in messageRepository.LoadMessages())
         {
             try
             {
                 messageRepository.DeleteMessage(msg);
+                deleted++;
             }
             catch (Exception ex)
             {
                 logger.Warning(ex, "Failure Deleting Message File {MessageFile}", msg.File);
+                failed++;
             }
         }
+
+        return failed == 0
+            ? $"Deleted {deleted} message(s)"
+            : $"Deleted {deleted} message(s); {failed} failed to delete";
     }
 
     [HttpDelete("{id}")]
-    public ActionResult Delete(string id)
+    [McpServerTool(Name = "delete_message")]
+    [Description("Deletes a received email message by id.")]
+    public string Delete(
+        [Description("The message id (as returned by list_messages)")] string id)
     {
-        var messageEntry = messageRepository.LoadMessages().FirstOrDefault(msg => msg.Name == id);
-        if (messageEntry == null)
-        {
-            return this.NotFound();
-        }
+        var messageEntry = this.GetMessageEntry(id);
 
         try
         {
@@ -74,32 +96,28 @@ public ActionResult Delete(string id)
         catch (Exception ex)
         {
             logger.Warning(ex, "Failure Deleting Message File {MessageFile}", messageEntry.File);
-            return this.StatusCode(500);
+            throw new McpException($"Failed to delete message '{id}'");
         }
 
-        return this.NoContent();
+        return $"Deleted message '{id}'";
     }
 
     [HttpGet("{id}")]
-    public async Task<ActionResult<MimeMessageEntry.DetailDto>> Get(string id)
+    [McpServerTool(Name = "get_message")]
+    [Description("Gets the full detail of a received email message by id: from/to/cc/bcc addresses, subject, text and HTML bodies, headers, and a manifest of MIME sections (body parts and attachments).")]
+    public async Task<MimeMessageEntry.DetailDto> Get(
+        [Description("The message id (as returned by list_messages)")] string id,
+        CancellationToken token = default)
     {
-        var messageEntry = messageRepository.LoadMessages().FirstOrDefault(msg => msg.Name == id);
-        if (messageEntry == null)
-        {
-            return this.NotFound();
-        }
+        var messageEntry = this.GetMessageEntry(id);
 
-        return MimeMessageEntry.DetailDto.CreateFrom(new MimeMessageEntry(messageEntry, (await messageLoader.GetAsync(messageEntry))!));
+        return MimeMessageEntry.DetailDto.CreateFrom(new MimeMessageEntry(messageEntry, (await messageLoader.GetAsync(messageEntry, token))!));
     }
 
     [HttpGet("{messageId}/raw")]
     public ActionResult DownloadRaw(string messageId)
     {
-        var messageEntry = messageRepository.LoadMessages().FirstOrDefault(msg => msg.Name == messageId);
-        if (messageEntry == null)
-        {
-            return this.NotFound();
-        }
+        var messageEntry = this.GetMessageEntry(messageId);
 
         var response = new FileStreamResult(System.IO.File.OpenRead(messageEntry.File), "message/rfc822")
                        {
@@ -121,13 +139,16 @@ public Task<ActionResult> DownloadSectionContent(string messageId, string conten
         return this.DownloadSection(messageId, sections => sections.FirstOrDefault(s => s.ContentId == contentId));
     }
 
+    MessageEntry GetMessageEntry(string id)
+    {
+        var messageEntry = messageRepository.LoadMessages().FirstOrDefault(msg => msg.Name == id);
+
+        return messageEntry ?? throw new MessageNotFoundException(id);
+    }
+
     async Task<ActionResult> DownloadSection(string messageId, Func<List<MimePart>, MimePart?> findSection)
     {
-        var messageEntry = messageRepository.LoadMessages().FirstOrDefault(msg => msg.Name == messageId);
-        if (messageEntry == null)
-        {
-            return this.NotFound();
-        }
+        var messageEntry = this.GetMessageEntry(messageId);
 
         var mimeMessage = new MimeMessageEntry(messageEntry, (await messageLoader.GetAsync(messageEntry))!);
         var sections = mimeMessage.MailMessage.BodyParts.OfType<MimePart>().ToList();

src/Papercut.Service/Application/Mcp/McpServerSettings.cs

@@ -0,0 +1,35 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using Microsoft.Extensions.Configuration;
+
+namespace Papercut.Service.Application.Mcp;
+
+public static class McpServerSettings
+{
+    public const string EnabledSettingKey = "EnableMcpServer";
+
+    public const string EndpointPath = "/mcp";
+
+    public static bool IsEnabled(ISettingStore settingStore, IConfiguration configuration)
+    {
+        var setting = settingStore.Get(EnabledSettingKey, configuration[EnabledSettingKey]);
+
+        return bool.TryParse(setting, out var enabled) && enabled;
+    }
+}