JMAP MCP サーバー

JMAP (JSON Meta Application Protocol) メールサーバーとやり取りするためのツールを提供する Model Context Protocol (MCP) サーバーです。Deno で構築されており、@htunnicliff/jmap-jam クライアントライブラリを使用しています。

機能

メール管理ツール

• メール検索: テキストクエリ、送信者/受信者フィルター、日付範囲、キーワードを使用してメールを検索します。すべてのフィルターは AND 条件で結合されます。

• メール取得: ID を指定して特定のメールを取得します（プロパティ選択可能）。

• スレッド取得: メールスレッド（会話チェーン）を取得します。

• メールのマーク付け: メールを既読/未読、フラグ付き/フラグなしに設定します。

• メールの移動: メールボックス間でメールを移動します。

• メールの削除: メールを完全に削除します。

メールボックス管理

• メールボックス取得: 階層構造をサポートしたすべてのメールボックス/フォルダーを一覧表示します。他のツールで必要なメールボックス ID を見つけるために使用します。

インクリメンタル同期

• メール変更の取得: 前回の状態以降に作成、更新、または削除されたメールの ID を取得します（状態ベースの差分追跡）。

• 検索更新の取得: 前回の検索クエリ以降の追加/削除を queryState に基づいて取得します。

メールの作成

• メール送信: プレーンテキストおよび HTML をサポートした新しいメールを作成して送信します。

• メールへの返信: 自動ヘッダー処理と全員への返信をサポートし、既存のメールに返信します。

主な機能

• jmap-jam を介した完全な JMAP RFC 8620/8621 準拠

• Zod スキーマによる包括的な入力バリデーション

• すべてのリスト操作に対するページネーションのサポート

• 効率的なポーリングのための状態ベースのインクリメンタル同期

• 豊富なエラーハンドリングと接続管理

• 機能ベースのツール登録（読み取り専用、送信）

• 強力な型定義を備えた TypeScript サポート

Related MCP server: bare-mcp

インストール

Claude Code プラグイン (推奨)

プラグインマーケットプレイスからインストールしてください：

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

次に、MCP サーバー設定で必要な環境変数を設定します。

前提条件

• Deno v1.40 以降

• JMAP 準拠のメールサーバー (例: Cyrus IMAP, Stalwart Mail Server, FastMail)

• 有効な JMAP 認証資格情報

セットアップ

お使いのエージェントに以下を追加してください：

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

FastMail を使用していない場合は、--allow-net 内の api.fastmail.com をお使いの JMAP サーバーのホスト名に置き換えてください。

使用方法

環境変数

利用可能なツール

get_mailboxes

メールボックス/フォルダーを ID、名前、メタデータとともに一覧表示します。search_emails (inMailbox) や move_emails (mailboxId) で必要なメールボックス ID を取得するために、最初にこれを呼び出してください。一般的な名前: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk。

パラメータ:

• parentId (オプション): 親メールボックス ID でフィルタリング

• limit (オプション): 最大結果数 (1-200, デフォルト: 100)

• position (オプション): ページネーションの開始位置

search_emails

フィルターを使用してメールを検索します。すべてのフィルターは AND 条件で結合されます。 メール ID のみが返されます。コンテンツを取得するには get_emails を使用してください。結果には get_search_updates によるインクリメンタル同期用の queryState が含まれます。

パラメータ:

• query (オプション): すべてのフィールドに対するテキスト検索

• body (オプション): メッセージ本文のみを検索

• from (オプション): 送信者のメールアドレスでフィルタリング

• to (オプション): 受信者のメールアドレスでフィルタリング

• subject (オプション): 件名のテキストでフィルタリング

• inMailbox (オプション): 検索対象のメールボックス ID (get_mailboxes から取得)

• hasKeyword (オプション): キーワードでフィルタリング (例: $seen, $flagged)

• notKeyword (オプション): キーワードで除外 (例: $seen, $draft)

• allInThreadHaveKeyword (オプション): スレッド内のすべてのメールがキーワードを持つ必要がある

• someInThreadHaveKeyword (オプション): スレッド内の少なくとも 1 つのメールがキーワードを持つ必要がある

• before (オプション): 指定日時より前のメールのみ (ISO 8601 日時)

• after (オプション): 指定日時より後のメールのみ (ISO 8601 日時)

• limit (オプション): 最大結果数 (1-100, デフォルト: 50)

• position (オプション): ページネーションの開始位置 (デフォルト: 0)

get_emails

ID を指定して特定のメールを取得します。必要なプロパティのみを要求するには properties を使用してください。すべてのプロパティを取得すると大きなペイロードが返されます。

パラメータ:

• ids: メール ID の配列 (1-50 ID)

• properties (オプション): 返す特定のプロパティ。推奨セット:

  • 概要: ["id", "subject", "from", "to", "receivedAt", "preview"]

  • 全文読み取り: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

  • 注意: 本文を取得するには、bodyValues と textBody/htmlBody の両方を含めてください。

get_threads

ID を指定してメールスレッドを取得します。スレッド ID は get_emails のレスポンス (threadId プロパティ) から取得します。スレッドごとのメール ID が返されます。コンテンツを取得するには、それらの ID に対して get_emails を使用してください。

パラメータ:

• ids: スレッド ID の配列 (1-20 ID)

get_email_changes

前回の状態以降に作成、更新、または削除されたメールの ID を取得します。get_emails レスポンスの state 文字列を使用してください。

パラメータ:

• sinceState: 前回の get_emails レスポンスからの状態文字列

• maxChanges (オプション): 返す変更の最大数 (1-500)

• fetchEmails (オプション): 変更された ID のメール詳細を自動取得する (デフォルト: false)

• properties (オプション): fetchEmails が true の場合に取得するプロパティ

get_search_updates

前回の検索クエリ以降の queryState 内の変更を取得します。元の search_emails 呼び出しと同じフィルターパラメータを使用する必要があります。

パラメータ:

• sinceQueryState: 前回の search_emails レスポンスからの queryState

• search_emails からのすべてのフィルターパラメータ (元のクエリと一致させる必要があります)

• maxChanges (オプション): 返す変更の最大数 (1-500)

mark_emails

メールを既読/未読、またはフラグ付き/フラグなしにマークします。

パラメータ:

• ids: メール ID の配列 (1-100 ID)

• seen (オプション): 既読 (true) または未読 (false) にマーク

• flagged (オプション): フラグ付き (true) またはフラグなし (false) にマーク

move_emails

メールを別のメールボックスに移動します。ターゲットのメールボックス ID を見つけるには get_mailboxes を使用してください。

パラメータ:

• ids: メール ID の配列 (1-100 ID)

• mailboxId: ターゲットのメールボックス ID (get_mailboxes から取得)

delete_emails

メールを完全に削除します（元に戻せません）。復元可能な削除を行うには、move_emails を使用してゴミ箱に移動することを推奨します。

パラメータ:

• ids: メール ID の配列 (1-100 ID)

send_email

新しいメールを送信します。textBody または htmlBody（あるいは両方）が必要です。

パラメータ:

• to: 受信者の配列 (name はオプション, email は必須)

• cc (オプション): CC 受信者の配列

• bcc (オプション): BCC 受信者の配列

• subject: メールの件名

• textBody (オプション): プレーンテキスト本文

• htmlBody (オプション): HTML 本文

• identityId (オプション): 送信元の JMAP ID (省略時はサーバーデフォルトを使用)

reply_to_email

既存のメールに返信します。To/CC、件名の「Re:」プレフィックス、およびスレッドヘッダー（In-Reply-To, References）を自動的に設定します。

パラメータ:

• emailId: 返信対象のメール ID

• replyAll (オプション): すべての元の受信者を含める (デフォルト: false)

• subject (オプション): カスタム返信件名 (デフォルトは Re: <元の件名>)

• textBody (オプション): プレーンテキスト本文

• htmlBody (オプション): HTML 本文

• identityId (オプション): 送信元の JMAP ID (省略時はサーバーデフォルトを使用)

JMAP サーバーの互換性

このサーバーは、以下を含む JMAP 準拠のメールサーバーで動作するはずです:

• Cyrus IMAP 3.0+

• Stalwart Mail Server

• FastMail (商用)

• Apache James (JMAP サポート付き)

開発

開発環境での実行

just watch          # Run with file watching
just start          # Run without watching

テスト

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

アーキテクチャ

このサーバーは以下を使用して構築されています:

• Deno: モダンな JavaScript/TypeScript ランタイム

• @modelcontextprotocol/sdk: MCP サーバーフレームワーク

• jmap-jam: 軽量で型定義された JMAP クライアント

• Zod: ランタイム型バリデーション

セキュリティ

• すべての入力は Zod スキーマを使用して検証されます

• 機密設定には環境変数を使用します

• シークレットはログに記録されたり、レスポンスで公開されたりすることはありません

• JMAP セキュリティのベストプラクティスに従っています

貢献

1. リポジトリをフォークする

2. フィーチャーブランチを作成する

3. 関数型プログラミングスタイルに従って変更を加える

4. 変更を徹底的にテストする

5. プルリクエストを送信する

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください。

関連プロジェクト

• jmap-jam - JMAP クライアントライブラリ

• Model Context Protocol - MCP 仕様

• JMAP RFC 8620 - JMAP コアプロトコル

• JMAP RFC 8621 - メール用 JMAP