stalwart-mail-mcp

Stalwart Mail MCP

チェコ語

Claude Desktop（または stdio に対応する任意の MCP クライアント）から、お使いの Stalwart メールサーバー上のメールボックスを操作できる MCP サーバーです。添付ファイルやスキャン画像を含むメールの検索と閲覧、スレッドへの返信、メールの送信、下書きの保存、連絡先の検索や追加ができます。

メールボックス固有の認証情報を使って JMAP で通信します。サーバーには何もインストールしません。

Claude Desktop ──stdio──▶ dist/index.cjs (Node, this MCP server)
                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)
                              ▼
                 https://mail.example.com/jmap   (reverse proxy → Stalwart)

リモートモードもあります。同じサーバーを Stalwart の隣で実行し、カスタムコネクターとして Claude に追加すれば、claude.ai、モバイルアプリ、あらゆるデスクトップチャットでメールボックスを利用できます。ユーザーは Stalwart 独自の OAuth を使ってサインインするため、サーバーに認証情報は保存されません。詳しくはdocs/remote.mdをご覧ください。

リバースプロキシ、公開するもの、共有メールボックス、家族やチーム向けのブランド版ビルドなど、小規模なセルフホスト構成での利用方法についてはdocs/small-infrastructure.mdをご覧ください。

ツール

ツール名には、既定で mail_ というプレフィックスが付きます（ブランド版ビルドでは変更できます）。

ツール	機能
mail_list_mailboxes	アカウント（自分用と共有）、件数付きフォルダー、許可された送信者、アドレス帳を表示します
mail_search_emails	全文／差出人／宛先／件名／フォルダー／日付／未読／添付ファイルの有無で検索するか、スレッド全体を取得します
mail_get_email	ID を指定してメッセージ全体を取得します（HTML をテキストに変換）。添付ファイルの番号付き一覧も表示します
mail_get_attachment	添付ファイルの内容を取得します。テキスト、ページごとの PDF、スキャン画像や撮影した書類の OCR、画像に対応し、ファイルをディスクに保存します
mail_send_email	新規メールまたは返信（in_reply_to_id、reply_all）を送信します。添付ファイルはディスクから指定します
mail_create_draft	同じ内容を下書きとして保存します
mail_send_draft / mail_delete_draft	ID を指定して下書きを送信／削除します
mail_search_contacts	すべてのアカウントのアドレス帳に加え、メール履歴にある差出人と宛先を検索します
mail_add_contact	連絡先を追加します（自分用または共有アドレス帳）

メールの送信はすぐに実行され、取り消せません。そのため、ツールの説明では、ユーザーから明示的な指示があった場合にのみ送信し、それ以外の場合は下書きを作成するようモデルに指示しています。

インストール

Claude Desktop（拡張機能）

最新リリースから stalwart-mail.mcpb をダウンロードして開くと、Claude Desktop がインストールを案内します。自分でビルドすることもできます。

npm install
./pack.sh                  # → stalwart-mail.mcpb
open stalwart-mail.mcpb    # Claude Desktop → Install

サーバーアドレス、メールアドレス、パスワードを入力してください。必要に応じて、言語と OCR 用の Mistral API キーも指定できます。パスワードはオペレーティングシステムのキーチェーンに保存されます。

任意の MCP クライアント（stdio）

サーバーは npm の stalwart-mail-mcp として、また MCP Registry の io.github.cybersmurf/stalwart-mail-mcp として公開されているため、リポジトリをチェックアウトする必要はありません。

{
  "mcpServers": {
    "stalwart-mail": {
      "command": "npx",
      "args": ["-y", "stalwart-mail-mcp"],
      "env": {
        "STALWART_URL": "https://mail.example.com",
        "STALWART_USER": "[email protected]",
        "STALWART_PASSWORD": "…"
      }
    }
  }
}

Claude Code：claude mcp add stalwart-mail --env STALWART_URL=https://mail.example.com --env [email protected] --env STALWART_PASSWORD=… -- npx -y stalwart-mail-mcp

Web 版 Claude、デスクトップチャット、スマートフォン

Stalwart の隣でサーバーを実行し（stalwart-mail-mcp --http または Docker イメージ）、その URL をカスタムコネクターとして追加します。手順はdocs/remote.mdをご覧ください。

設定

変数	意味
STALWART_URL	サーバーの公開アドレス。例：https://mail.example.com（必須）
STALWART_USER	サインインするメールボックス（必須）
STALWART_PASSWORD	メールボックスのパスワードまたはアプリパスワード。Basic 認証として送信されます
STALWART_TOKEN	パスワードの代わりに使う OAuth アクセストークン。Bearer として送信されます
MAIL_LANG	auto（デフォルト：マシンの言語。未対応の場合は英語）またはロケールコード
MAIL_TOOL_PREFIX	ツール名のプレフィックス。デフォルトは mail
MAIL_BRAND	サーバーの表示名。デフォルトは Stalwart Mail
MAIL_DOWNLOAD_DIR	添付ファイルの保存先。デフォルトは ~/Downloads/Mail-Attachments
MAIL_TIMEZONE	出力する日付に使用する IANA タイムゾーン。デフォルトはマシンのタイムゾーン
MAIL_OCR_PROVIDER、MAIL_OCR_API_KEY、MAIL_OCR_MODEL、MAIL_OCR_BASE_URL	スキャンを読み取るプロバイダー。OCR プロバイダーを参照してください
MISTRAL_API_KEY	ショートカット：これだけを設定すると、スキャンは Mistral OCR に送信されます
MAIL_ALLOW_SEND	false にすると send_email と send_draft が無効になります
MAIL_ALLOW_DRAFTS	false にすると create_draft と delete_draft が無効になります
MAIL_ALLOW_CONTACT_EDIT	false にすると add_contact が無効になります
MAIL_ALLOW_ATTACHMENTS	false にすると get_attachment が無効になります
MAIL_SAVE_ATTACHMENTS	false の場合、開いた添付ファイルは読み取りのみで、ディスクには何も書き込まれません

許可される操作

すべての機能は拡張機能の設定（または上記の環境変数）で切り替えられ、デフォルトではすべて有効です。オフにした機能はツールとして一切提供されないため、クライアントが承認プロンプトで記憶している内容にかかわらず、その状態が維持されます。

• 送信をオフにする → Claude がメールボックスを読み取り、下書きを作成できますが、送信はできません。
• 送信、下書き、連絡先の編集をオフにする → 読み取り専用のメールボックスになります。
• 添付ファイルの保存をオフにする → get_attachment は一時コピーからファイルを読み取り、読み取り専用として注記されます。保存をオンにするとダウンロードフォルダーに書き込み、書き込みツールとして注記されます。クライアントは承認を求める際に、これを別の扱いにすることがあります。

承認自体（「一度だけ許可／常に許可」）を管理するのは、このサーバーではなくクライアントです。Claude Desktop では、拡張機能の設定でツールごとに設定します。ツールの定義を変更するアップデート後に、クライアントが再度確認することがあります。

添付ファイルと OCR

mail_get_attachment はファイルをダウンロードし、モデルが読み取れる形式で返します。

• テキストファイルはテキストとして返し、HTML はテキストに変換します。
• PDF はページごとにテキストとして返します（長い PDF には page_from／page_to を指定します）。
• テキストレイヤーのない PDF ページ（スキャン）と写真は、選択したOCR プロバイダーに送信されます。結果は表を含む Markdown で、該当ページには (OCR) と表示されます。スキャンとテキストが混在する PDF では、スキャンページのみを送信します。
• 画像は画像として返されます。約 600 kB を超える画像や HEIC 形式の画像は、macOS では sips を使って縮小されます。
• その他の形式（docx、xlsx、zip など）は保存のみ行われ、パスが返されます。

プロバイダーが設定されていない場合、または ocr: false の場合、スキャンは注記とともに 1 ページ目の画像として返されます（macOS）。このサーバーでメールサーバー以外の場所にコンテンツが送信されるのは OCR のみです。選択したプロバイダーに送信するか、ローカルモデルを使って一切送信しないかを選べます。

OCR プロバイダー

MAIL_OCR_PROVIDER	内容	必要なもの	PDF の読み取り
auto（デフォルト）	MISTRAL_API_KEY が設定されていれば Mistral、アドレスとモデルが設定されていればカスタムサーバー、それ以外はオフ	—	—
mistral	Mistral OCR（mistral-ocr-latest）	キー	直接
anthropic	公式 SDK 経由の Claude（デフォルトモデル claude-opus-5-5）	キー	直接
openai、openrouter、gemini	ホスト型の OpenAI 互換ビジョンチャット API	キー＋モデル	ページ画像
ollama、lmstudio	localhost 上のローカルモデル	モデル	ページ画像
custom	その他の OpenAI 互換サーバー	MAIL_OCR_BASE_URL＋モデル	ページ画像
off	OCR を使用しない	—	—

MAIL_OCR_API_KEY、MAIL_OCR_MODEL、MAIL_OCR_BASE_URL で設定を補います。例：

MAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # fully local
MAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<a vision model>
MAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…
MAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…

画像のみを受け付けるプロバイダーには、PDF から取り出した各スキャンページが PNG として送信されます（スキャン画像そのものを 2000 px に拡大縮小したものです）。ページ全体がひとつの画像でない場合は送信できず、未読として報告されます。Mistral と Anthropic はすべての PDF を読み取ります。ページは一度に 3 ページずつ送信されます。

留意点：ローカルモデルでは、情報量の多いページの処理に 1 分以上かかることがあり、クライアントのツールタイムアウトを超える可能性があります。長いスキャンはページ範囲を指定して読み取ってください。汎用ビジョンモデルは適切に文字起こしできますが、他の OCR と同様、図表のセルを誤って配置することがあります。preview: true を指定するとページ画像が追加され、モデルが確認できるようになります。anthropic では、リクエストが拒否された場合、現在の Claude モデルのフォールバックモデルを使ってサーバー側で再試行します（fallbacks: "default"）。

node test/live-ocr.mjs を実行すると、環境で設定されたプロバイダーをスキャン済みのフィクスチャ（または独自のファイル）に対して実行し、結果を出力します。

言語

ツールのタイトル、説明、出力、エラーメッセージはローカライズされています。英語が原文で、チェコ語は手作業で作成されています。ドイツ語、スペイン語、フランス語、イタリア語、オランダ語、ポーランド語、ポルトガル語、スロバキア語は機械翻訳で、まだネイティブスピーカーによる確認を受けていません。修正を歓迎します。

言語を追加または修正するには、src/locales/<code>.ts を編集します（en.ts をコピーし、{placeholders} と改行を維持してください）。その後、src/locales/index.ts に登録します。ロケールの一部だけを翻訳してもかまいません。キーが欠けている場合は英語にフォールバックします。npm run test:offline で、すべてのロケールのキーが英語と一致するか確認できます。

ブランド付きビルド（プリセット）

家族やチーム向けに、サーバーアドレスがあらかじめ入力され、メールアドレスとパスワードだけを入力すればよい拡張機能を配布できます。プリセットは独自の manifest.json（および任意で icon.png）を含むフォルダーです。presets/example を参照してください。

./pack.sh --preset /path/to/preset     # → /path/to/preset/<name>.mcpb

プリセットのマニフェストでは、env を通じて MAIL_TOOL_PREFIX、MAIL_BRAND、MAIL_LANG、MAIL_DOWNLOAD_DIR を設定し、server_url にデフォルト値を指定します。Claude Desktop が新しいビルドをアップデートとして扱うように、プリセットの name は変更しないでください。

テスト

npm run test:offline       # no mailbox needed: fake JMAP + fake OCR, the real server over stdio
MISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # also sends the fixtures to the real OCR
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # real mailbox
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # also sends a mail to yourself

オフラインテストでは、添付ファイル、OCR、ツールのプレフィックス、言語選択、ロケールの整合性を確認します。スモークテストでは下書きを作成して削除します。--send を指定すると、メールボックスにテストメッセージが 1 件残ります。

知っておくとよいこと

• パスワードを間違えると、数回の試行後に Stalwart によって IP が BAN されます。 サーバーは起動時ではなく最初のツール呼び出し時にサインインするため、クライアントを再起動しても BAN されません。誤ったパスワードでツールを繰り返し呼び出すと BAN されます。
• Stalwart 0.16 向けに構築され、同バージョンで使用されています。メール機能は標準の RFC 8620/8621 を使用しているため、他の JMAP サーバーでも動作する可能性がありますが、テストはしていません。連絡先には JMAP for Contacts（RFC 9610）が必要です。
• "inMailbox": null を指定した Email/query は Stalwart に拒否されます。フィルターを省略するか、ID を指定する必要があります。
• 拡張機能のバンドルは 1 つの CommonJS ファイル（約 3.8 MB）で、その大部分を unpdf の pdf.js が占めます。package.json で "type": "module" が指定されているため、.cjs 拡張子が重要です。
• Claude Desktop のツール結果は約 1 MB に制限されているため、インライン画像の上限は 600 kB です。

ライセンス

MIT