Postmark MCP server

The Postmark MCP server provides a Model Context Protocol implementation for sending emails through Postmark's email services. It offers a straightforward way to integrate email capabilities into your applications with minimal configuration.

Installation

Prerequisites

• Node.js (v16 or higher recommended)
• A Postmark account and server token

Installation Steps

1. Clone the repository:

git clone https://github.com/ActiveCampaign/postmark-mcp
cd postmark-mcp

2. Install dependencies:

npm install

3. Configure environment variables:
   • Copy the example environment file:

cp .env.example .env

• Edit the .env file with your Postmark credentials:

Variable	Description	Required
POSTMARK_SERVER_TOKEN	Your Postmark server API token	Yes
DEFAULT_SENDER_EMAIL	Default sender email address	Yes
DEFAULT_MESSAGE_STREAM	Postmark message stream (e.g., 'outbound')	Yes

4. Start the server:

npm start

Usage

MCP Configuration

When using this server with Claude or Cursor, add the following to your MCP configuration:

{
  "mcpServers": {
    "postmark": {
      "command": "node",
      "args": ["path/to/postmark-mcp/index.js"],
      "env": {
        "POSTMARK_SERVER_TOKEN": "your-postmark-server-token",
        "DEFAULT_SENDER_EMAIL": "[email protected]",
        "DEFAULT_MESSAGE_STREAM": "your-message-stream"
      }
    }
  }
}

Available Tools

Email Management

Send a Basic Email

Example prompt:

Send an email using Postmark to [email protected] with the subject "Meeting Reminder" and the message "Don't forget our team meeting tomorrow at 2 PM. Please bring your quarterly statistics report (and maybe some snacks).""

The server will process a payload like:

{
  "to": "[email protected]",
  "subject": "Meeting Reminder",
  "textBody": "Don't forget our team meeting tomorrow at 2 PM. Please bring your quarterly statistics report (and maybe some snacks).",
  "htmlBody": "HTML version of the email body",
  "from": "[email protected]",
  "tag": "meetings"
}

Send an Email with Template

Example prompt:

Send an email with Postmark template alias "welcome" to [email protected] with the following template variables:
{
  "name": "John Doe",
  "product_name": "MyApp",
  "login_url": "https://myapp.com/login"
}

The server will process a payload like:

{
  "to": "[email protected]",
  "templateAlias": "welcome",
  "templateModel": {
    "name": "John Doe",
    "product_name": "MyApp",
    "login_url": "https://myapp.com/login"
  },
  "from": "[email protected]",
  "tag": "onboarding"
}

Template Management

List Templates

Example prompt:

Show me a list of all the email templates available in our Postmark account.

Statistics & Tracking

Get Delivery Statistics

Example prompt:

Show me our Postmark email delivery statistics from 2025-05-01 to 2025-05-15 for the "marketing" tag.

The server will process a payload like:

{
  "tag": "marketing",
  "fromDate": "2025-05-01",
  "toDate": "2025-05-15"
}

Technical Details

Automatic Configuration

All emails sent through this server have these settings automatically applied:

• Open tracking enabled
• Link tracking enabled for both HTML and text
• Default message stream from environment variable

Error Handling

The server implements comprehensive error handling including:

• Environment variable validation
• Graceful shutdown
• API error handling
• Secure logging (no sensitive data exposure)

For more information about the Postmark API, visit Postmark's Developer Documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "Postmark" '{"command":"node","args":["index.js"],"env":{"POSTMARK_SERVER_TOKEN":"","DEFAULT_SENDER_EMAIL":"","DEFAULT_MESSAGE_STREAM":"outbound"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "Postmark": {
            "command": "node",
            "args": [
                "index.js"
            ],
            "env": {
                "POSTMARK_SERVER_TOKEN": "",
                "DEFAULT_SENDER_EMAIL": "",
                "DEFAULT_MESSAGE_STREAM": "outbound"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "Postmark": {
            "command": "node",
            "args": [
                "index.js"
            ],
            "env": {
                "POSTMARK_SERVER_TOKEN": "",
                "DEFAULT_SENDER_EMAIL": "",
                "DEFAULT_MESSAGE_STREAM": "outbound"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect