Postmark MCP

🚀 Postmark MCP Server

このサーバーは、Postmarkのメールサービスに対応したModel Context Protocol (MCP) サーバーの実装です。Postmarkを介したメール送信を簡単に行うことができます。

✨ 主な機能

• Postmarkを介してメールを送信するためのModel Context Protocol (MCP) サーバーを提供します。
• 環境変数を使用した簡単な設定が可能です。
• 包括的なエラーハンドリングと正常なシャットダウンを実現します。
• セキュアなログ記録方法を採用しており、機密データの漏洩を防ぎます。
• 自動的なメール追跡設定が可能です。

📦 インストール

必要条件

• Node.js (v16以上を推奨)
• Postmarkアカウントとサーバートークン

セットアップ手順

1. リポジトリをクローンする:

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

2. 依存関係をインストールする:

   npm install
   

3. 環境変数を設定する:

   • .env.example を .env にコピーします。

     cp .env.example .env
     

   • .env を編集し、Postmarkの認証情報と設定を入力します。

   変数名	説明	必須
   POSTMARK_SERVER_TOKEN	PostmarkサーバーのAPIトークン	はい
   DEFAULT_SENDER_EMAIL	デフォルトの送信者メールアドレス	はい
   DEFAULT_MESSAGE_STREAM	Postmarkのメッセージストリーム (例: 'outbound')	はい

4. サーバーを起動する:

   npm start
   

Cursor Deeplinkを使用したクイックインストール

以下のボタンをクリックすることで、Cursor内でこのMCPサーバーをすぐにインストールできます。

⚠️ 重要提示

ボタンをクリックした後、以下の設定を行う必要があります。

1. MCP設定で POSTMARK_SERVER_TOKEN を設定します。
2. MCP設定で DEFAULT_SENDER_EMAIL を設定します。
3. MCP設定で DEFAULT_MESSAGE_STREAM を設定します (デフォルトは "outbound")。

💻 使用例

ClaudeとCursorのMCP設定例

{
  "mcpServers": {
    "Postmark": {
      "command": "your-node-path", // which node
      "args": ["/Users/your-name/your-location/postmark-mcp/index.js"], // realpath index.js
      "env": {
        "POSTMARK_SERVER_TOKEN": "your-postmark-server-token",
        "DEFAULT_SENDER_EMAIL": "your-default-sender-email",
        "DEFAULT_MESSAGE_STREAM": "your-default-message-stream"
      }
    }
  }
}

📚 ドキュメント

ツールリファレンス

このセクションでは、Postmark MCPサーバーツールの完全なリファレンスを提供します。各ツールの使用例と期待されるペイロードを示します。

目次

• メール管理ツール
  • sendEmail
  • sendEmailWithTemplate
• テンプレート管理ツール
  • listTemplates
• 統計と追跡ツール
  • getDeliveryStats

メール管理ツール

1. sendEmail

単一のテキストメールを送信します。

使用例:

Postmarkを使用して、受信者recipient@example.comに件名 "Meeting Reminder" でメッセージ "Don't forget our team meeting tomorrow at 2 PM. Please bring your quarterly statistics report (and maybe some snacks)." を送信します。

期待されるペイロード:

{
  "to": "recipient@example.com",
  "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": "sender@example.com", // オプション、指定されない場合は DEFAULT_SENDER_EMAIL を使用
  "tag": "meetings" // オプション
}

レスポンス形式:

Email sent successfully!
MessageID: message-id-here
To: recipient@example.com
Subject: Meeting Reminder

2. sendEmailWithTemplate

事前定義されたテンプレートを使用してメールを送信します。

使用例:

Postmarkのテンプレートエイリアス "welcome" を使用して、顧客customer@example.comに以下のテンプレート変数を含むメールを送信します。
{
  "name": "John Doe",
  "product_name": "MyApp",
  "login_url": "https://myapp.com/login"
}

期待されるペイロード:

{
  "to": "customer@example.com",
  "templateId": 12345, // templateId または templateAlias のどちらか一方を指定する必要がありますが、両方を指定することはできません
  "templateAlias": "welcome", // templateId または templateAlias のどちらか一方を指定する必要がありますが、両方を指定することはできません
  "templateModel": {
    "name": "John Doe",
    "product_name": "MyApp",
    "login_url": "https://myapp.com/login"
  },
  "from": "sender@example.com", // オプション、指定されない場合は DEFAULT_SENDER_EMAIL を使用
  "tag": "onboarding" // オプション
}

レスポンス形式:

Template email sent successfully!
MessageID: message-id-here
To: recipient@example.com
Template: template-id-or-alias-here

テンプレート管理ツール

3. listTemplates

利用可能なすべてのテンプレートを一覧表示します。

使用例:

Postmarkアカウントで利用可能なすべてのメールテンプレートのリストを表示してください。

レスポンス形式:

📋 Found 2 templates:

• Basic
  - ID: 12345678
  - Alias: basic
  - Subject: none

• Welcome
  - ID: 02345679
  - Alias: welcome
  - Subject: none

統計と追跡ツール

4. getDeliveryStats

メールの配信統計を取得します。

使用例:

2025年5月1日から2025年5月15日までの "marketing" タグのPostmarkメール配信統計を表示してください。

期待されるペイロード:

{
  "tag": "marketing", // オプション
  "fromDate": "2025-05-01", // オプション、YYYY-MM-DD形式
  "toDate": "2025-05-15" // オプション、YYYY-MM-DD形式
}

レスポンス形式:

Email Statistics Summary

Sent: 100 emails
Open Rate: 45.5% (45/99 tracked emails)
Click Rate: 15.2% (15/99 tracked links)

Period: 2025-05-01 to 2025-05-15
Tag: marketing

🔧 技術詳細

自動設定

すべてのメールは自動的に以下の設定が適用されます。

• TrackOpens: true
• TrackLinks: "HtmlAndText"
• メッセージストリームは DEFAULT_MESSAGE_STREAM 環境変数から取得します。

エラーハンドリング

サーバーは包括的なエラーハンドリングを実装しています。

• すべての必須環境変数の検証
• SIGTERMとSIGINTでの正常なシャットダウン
• API呼び出しの適切なエラーハンドリング
• ログに機密情報を露出させない
• 一貫したエラーメッセージのフォーマット

ログ記録

• 適切なログレベルを使用します (info は通常の操作、error はエラー時)
• ログから機密情報を除外します
• 明確な操作ステータスと結果を提供します

Postmark APIの詳細については、Postmarkの開発者ドキュメント を参照してください。