cfmail · エージェントに、単独で使えるメールボックスを

English | 简体中文

これは何か

目標はシンプルです。エージェントが自分でメールの受信と送信を行い、人間が転送、承認、あるいは「送信」ボタンをクリックする必要がないことです。 これは Cloudflare 上で動作し、Web UI はありません — あなたが閲覧する受信箱ではなく、AI/プログラムが自分専用として使うメールボックスです。

anything@your-domain 宛てのメールは自動的に受け取られ、保存されます。エージェントはそれを検索し、本文全体を読み、返信し、添付ファイルを転送します。あなたがメールを転送する必要も、エージェントがあなたの送信クリックを待つ必要もありません。

Someone emails you ──▶ Cloudflare receives it ──▶ parsed automatically, stored in a database and object storage
                                                              │
Agent ──asks a question / sends mail──▶ cfmail CLI (or MCP directly) ──▶ this service's API ──┘

初期費用はほぼゼロ — Cloudflare と Resend の無料枠で十分で、どちらもクレジットカードは不要です：

1人または少数のエージェントが使う小規模プロジェクトでは、これらの上限に達するのは難しいでしょう。実際にボリュームが増えたら後でアップグレードすればよいのです。

こんな場面に適しています：

• エージェントに本当に自分専用のメールボックスを与え、「受信 → 理解 → 返信/転送」のループ全体を、間に手作業を挟まずに完結させる。

• 自分のドメインで認証コード、通知、請求書、領収書を受信し、AIに見つけて整理してもらう。

• メール（本文と添付ファイル）を定期的にローカルディスクへ同期し、新しいメールが届いた瞬間にクリック可能なローカルファイル付きのチャットメッセージがプッシュされるようにする。

技術的な詳細（データベーススキーマ、検索設計、コンポーネント構成、二重送信バックエンド設計）は ARCHITECTURE.md にあります。

このドキュメントには2つのパートがあります。セットアップ — サービスを自分の Cloudflare アカウントにデプロイする方法、および使用方法 — デプロイ後に、エージェントにメールの送受信を使わせる方法です。

Related MCP server: gmail-mcp

セットアップ: Cloudflare へのデプロイ（約10分）

すべてはあなた自身の Cloudflare アカウント内で行われます。メールは常にあなたのアカウント内にのみ保管され、他の誰もアクセスできません。

必要なもの

1. Cloudflare アカウント（無料プランで十分です）。

2. そのアカウントに追加済みのドメイン（メールの受信とサービスへのアクセスの両方に使います）。

3. ローカルにインストールされた Node.js 18 以降。

ステップ 0: コードを取得し、ログインし、ローカル設定を作成する

git clone <this-repo> && cd cfmail
npm install
npx wrangler login                       # log into your Cloudflare account in the browser
cp wrangler.jsonc wrangler.local.jsonc   # your private config, never pushed to the repo

あなたのアカウントに関連するもの（ドメイン、データベース ID）はすべて wrangler.local.jsonc に記載します。これはすでに gitignore されており、以下のすべてのコマンドが自動的に読み込みます。

ステップ 1: データベースを作成する（メールのメタデータと本文を保存）

npx wrangler d1 create email_db

このコマンドは database_id を出力します。それを wrangler.local.jsonc の d1_databases[0].database_id にコピーしてください。

ステップ 2: オブジェクトストレージを作成する（生のメールと添付ファイルを保存）

npx wrangler r2 bucket create email-store

ステップ 3: ドメインを設定する

wrangler.local.jsonc を開き、routes[0].pattern を希望のサブドメインに変更します（例: mail.yourdomain.com。Cloudflare アカウント内のドメインである必要があります）。このアドレスがエージェントの接続先になります。

ステップ 4: テーブルを作成し、アクセスパスワードを設定し、デプロイする

npm run db:remote                        # create the tables
npx wrangler secret put MCP_TOKEN        # set an access password (see below)
npm run deploy                           # deploy

アクセスパスワード: そのコマンドを実行したら、十分に長いランダム文字列をパスワードとして貼り付けます — openssl rand -hex 32 で生成できます。エージェントが接続するにはこのパスワードが必要です。絶対に漏洩させないでください。ローテーションするには、コマンドを再実行するだけで、古いパスワードはすぐに使えなくなります。

ステップ 5: 受信メールをこのサービスにルーティングする

あなたのドメイン宛てのすべてのメールをこのサービスに送ります（一度だけの設定です）：

# replace <ZONE_ID> with your domain's Zone ID, and <API_TOKEN> with a Cloudflare API token that has "Email Routing edit" permission
curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/email/routing/rules/catch_all" \
  -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" \
  --data '{"enabled":true,"name":"catch-all to worker","matchers":[{"type":"all"}],"actions":[{"type":"worker","value":["cloudflare-email"]}]}'

代わりにダッシュボードでのクリック操作を好む場合は: Cloudflare ダッシュボード → あなたのドメイン → Email Routing → Catch-all → アクション「Send to a Worker」→ cloudflare-email を選択。

このドメインで Email Routing を有効にしたことがない場合は、まずダッシュボードで有効にしてください（メール配信に必要な DNS レコードが自動的に追加されます）。

完了！ anything@your-domain 宛てのメールが受け取られるようになり、サービスは https://your-subdomain で稼働しています。確認するには: test@your-domain にテストメールを送信し、数秒以内に npx wrangler tail cloudflare-email が処理中の様子を表示するはずです。以下の「使用方法」を設定すれば、エージェントがそれを見つけられるようになります。

任意: 送信を有効にする

このステップをスキップすると、サービスはメールの受信のみで送信はできません。サポートされているバックエンドは2つあり、デフォルトは Resend です：

オプション1: Resend（推奨）

1. Resend にサインアップし、ドメインを追加します — ルートドメイン（yourdomain.com）を直接使い、サブドメインは不要です。

2. 提供される3つの DNS レコードを Cloudflare DNS に追加します：

   種別	名前	値	プロキシ
   MX	send	Resend から提供されるアドレス、優先度10	—
   TXT	send	v=spf1 include:amazonses.com ~all	—
   TXT	resend._domainkey	Resend から提供される DKIM 公開鍵	DNS のみ（グレークラウドにする）

   この MX レコードは send.yourdomain.com に置かれるため、ルートドメインの Email Routing と競合しません。DKIM レコードはプロキシをオフにする必要があります — プロキシを有効にしたままでは検証に失敗します。

3. キーをシークレットとして設定します: npx wrangler secret put RESEND_API_KEY -c wrangler.local.jsonc

無料枠は3,000通/月、100通/日です — 始めるには十分です。成長に応じて有料化するか、以下のオプションに切り替えてください。

オプション2: Cloudflare の組み込み送信機能: wrangler.local.jsonc に "send_email": [{ "name": "EMAIL" }] があることを確認し（テンプレートにすでに含まれています）、Cloudflare の Email ダッシュボードでドメインの Email Sending オンボーディングを一度実行します。Email Routing → Destination addresses の下で既に検証済みのアドレスにのみ送信する場合は、オンボーディングを完全にスキップして、すぐに無料で送信できます。

どちらも設定していない場合、送信すると「no send backend available」という、何を設定すべきかを説明するメッセージが返ります。受信と照会は影響を受けません。送信の詳細（添付ファイルのサイズ制限、送信者制限、障害のデバッグ方法）については、ARCHITECTURE.md と cli/README.md を参照してください。送信に失敗した場合、エージェントがエラーコードを読んで何が問題かを教えてくれるので、これらの制限を事前に覚えておく必要はありません。

デプロイ後の継続的なメンテナンス

npx wrangler tail cloudflare-email        # tail incoming mail and errors live
npx wrangler secret put MCP_TOKEN         # rotate the access password
npx wrangler d1 execute email_db --remote --command "SELECT id,subject,from_addr,date FROM emails ORDER BY date DESC LIMIT 10"

wrangler.local.jsonc はあなたのマシンにしか存在しません — うっかり削除しないでください。削除した場合は「ステップ 0」をやり直し、データベース ID とドメインを再入力してください。

使用方法: エージェントにメールを送受信させる

デプロイ後、エージェントに接続する方法は3つあります。推奨は Skills の利用です — 最も手間がかからず、「エージェントが自分でメールを処理する」という目標に最も近い方法です。

推奨: Skills を使う（推奨）

skills/ ディレクトリには、エージェントに cfmail コマンドラインツールの使い方を教える2つのスキルがあります：

skills/
  email-inbox/   for a regular user: read and send mail with a bound Key
  email-admin/   for an admin: open mailboxes, issue/revoke Keys, configure new-mail alerts

この2つは連携して動作します。管理者は email-admin を使ってメールボックスアドレス用の Key を発行し、ユーザーはその Key を email-inbox に設定してメールを送受信します。

ステップ 0: cfmail をインストールする（Node 20 以降が必要です）：

npm install -g cfmail

ステップ 1: スキルをエージェントのスキルディレクトリにコピーする。 Claude Code の場合は .claude/skills/ です：

cp -r skills/email-inbox  your-project/.claude/skills/
cp -r skills/email-admin  your-project/.claude/skills/

skills/ ディレクトリ全体をシンボリックリンクすることもできます: ln -s /path/to/cfmail/skills your-project/.claude/skills。

ステップ 2（管理者）: メールボックスを開く：

cfmail admin setup --base https://your-subdomain --key <admin-MCP_TOKEN>   # one-time
cfmail admin create-key alice@your-domain                                 # prints a plaintext Key, shown only once

他の管理者コマンド: list-keys（発行済みの確認）、delete-key <address>（失効）、webhook --set whk_xxx（新着メールをチャットにプッシュ、任意 — cli/README.md を参照）。

ステップ 3（ユーザー）: その Key を設定する：

cfmail setup --base https://your-subdomain --email alice@your-domain --key <the-key-from-step-2>

設定が完了したら、エージェントに話しかけるだけです：

• 「新しいメールがないか確認して」 / 「その認証コードのメールを見つけて」

• 「その請求書メールに返信して、受け取ったことを確認して」

• 「その添付ファイルを経理に転送して」

エージェントは自分で適切なコマンドを選び、本文全体を読み、添付ファイルを取得し、必要に応じて返信します。メールは常に Key に紐づいたアドレスから送信されます — これはサーバー側で強制されており、変更できません。

さらに、メールをローカルディスクに同期し、新しいメールが届いたらクリック可能なファイルリンク付きのチャットプッシュを受け取りたい場合 — それはスキルの流れとは別の、任意のアドオンです：

cfmail sync --dir ~/cfmail --notify whk_your-key

launchd/cron でスケジュールに登録します。ディレクトリ構成、重複排除ルール、admin webhook との違いはすべて cli/README.md にあります。

セキュリティ上の注意: email-admin は最高権限の管理者キーを保持します — 管理者自身のマシンにのみ置き、通常のユーザーには絶対に渡さないでください。

代替: cfmail コマンドラインを直接使う

スキルを使わずに、エージェント（またはあなた）がコマンドを実行することもできます：

cfmail unread                                              # fetch the latest unread mail
cfmail search "invoice"                                    # full-text search, Chinese included
cfmail read <email-id>                                     # read the full text and attachment list
cfmail send --to a@x.com --subject "subject" --text "body"  # send one
cfmail reply <email-id> --text "reply text"                 # reply within the original thread
cfmail config                                              # see which mailbox this config points at

1台のマシンで複数のメールボックスを管理する、複数のエージェントを同時に実行する、ローカルアーカイブの構成、すべてのフラグ — 完全なリファレンスは cli/README.md にあります（すべてのコマンドが --help にも対応しています）。

代替: CLI をスキップして、サービスを MCP として直接接続する

CLI をインストールしたくない場合は、MCP 対応の AI クライアントをサービスに直接向けることができます：

claude mcp add --transport http email https://your-subdomain/mcp \
  --header "Authorization: Bearer your-password"

他の MCP クライアントでは設定ファイルを使います：

{
  "mcpServers": {
    "email": {
      "url": "https://your-subdomain/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

接続後は、自然言語で尋ねるだけです。「'invoice' を含むメールを検索して」「最初のメールを開いて添付ファイルをダウンロードして」— 内部では search_emails / list_emails / get_email / get_attachment / send_email のようなツールが使われ、AI が自動的に選択します。名前を覚えておく必要はありません。この方法ではローカルアーカイブや複数メールボックスの管理はできません — これらは cfmail 限定です。

FAQ

• サービス URL が読み込めない / 接続がリセットされる: デフォルトの *.workers.dev は使わないでください（一部の地域ではブロックされています）— 自分のドメインを使ってください（このプロジェクトのデフォルト動作です）。

• 送信したテストメールがバウンスした（550 SPF）: それは送信者側の検証の問題です。通常のメールボックス（Gmail、QQ、Outlook など）からの送信には影響しません。

• 送信したばかりのメールがまだ表示されない: 受信とインデックス化の間に数秒の遅延があります — 待ってもう一度確認するか、npx wrangler tail cloudflare-email で届いたかどうかを確認してください。

• 401 が返る: Authorization: Bearer your-password が正しく設定されているか確認してください。

コントリビューター向け: ローカル開発

cp .dev.vars.example .dev.vars                 # fill in a local access password
npm run db:local                               # create local database tables
npm run dev                                     # start locally on :8787
MCP_TOKEN=your-local-password node scripts/mcp-smoke.mjs    # smoke-test the local API
npm test                                        # unit tests
npm run typecheck                               # type checking

本番環境に対するスモークテスト: BASE="https://your-subdomain" TOKEN="your-password" node scripts/remote-check.mjs

ライセンス

MIT — 自由に使用、変更、再配布できます。