Gmail Postmaster Tools

Gmail Postmaster Tools MCP

Gmail Postmaster Tools API（v2） 用の MCP サーバーです。Claude、Cursor、または任意の MCP クライアントから、ドメイン、送信者のコンプライアンス状況、Gmail のトラフィック指標を照会できます。

これは、実際にメールを送信する方向けの独自の認証情報を用意するツールです。ご自身の Google OAuth クライアントを用意すると、サーバーがローカルでサインインを実行します。ホストされることはなく、データがマシンの外に出ることもありません。

Google Cloud プロジェクトを設定せずに利用したいですか？その場合は Postmaster+ をご利用ください。ホスト型で、複数のプロバイダー（Gmail + Outlook など）に対応し、検証、履歴、アラート機能も備えています。

OptiPub の Postmaster+ チームが開発・保守しています。

利用できる機能

• list_domains / get_domain — 登録済みのドメインとその確認状況
• get_compliance_status — SPF、DKIM、DMARC、アライメント、メッセージ形式、DNS レコード、TLS 暗号化、ユーザー報告の迷惑メール率、ワンクリック登録解除および登録解除の尊重状況
• query_domain_stats — 任意の期間における迷惑メール率、認証成功率（SPF/DKIM/DMARC）、TLS 暗号化率、配信エラー、フィードバックループの指標
• gpt_authenticate / gpt_auth_status / gpt_sign_out

注：Postmaster Tools v2 はトラフィック指標とコンプライアンスに対応しています。ドメインおよび IP の評価は v2 の対象外です。

前提条件：Google OAuth クライアントを作成する（初回のみ、約 5 分）

Google はこの API 用の共有公開クライアントを提供していないため、Google Cloud OAuth クライアントが必要です。

1. Google Cloud Console にアクセスし、プロジェクトを作成（または選択）します。
2. APIs & Services → Library を開き、「Gmail Postmaster Tools API」を検索して有効化します。
3. APIs & Services → OAuth consent screen を開きます（Google Auth Platform にリダイレクトされます）。プロジェクトがまだ設定されていない場合は、Get started をクリックして、App name とサポート用メールアドレスを設定し、Audience = External にして連絡先メールアドレスを入力します。すでに設定済みの場合はタブが表示されるので、次の手順に進みます。
4. Audience タブを開きます。User type = External の場合は、Test users → + Add users からご自身の Google アドレスを追加し、Save をクリックします（ステータスはTestingのままにしてください。アプリの確認なしで最大 100 人まで利用できます）。User type = Internal（Workspace 組織のプロジェクト）の場合、テストユーザーの追加は不要で、組織のユーザーはそのままサインインできます。
5. Clients タブ（または APIs & Services → Credentials）を開き、Create client → アプリケーションの種類 Desktop app → Create の順に選択します。
6. Client ID と Client secret をコピーします。

インストール時に、この拡張機能の設定にこれら 2 つの値を入力します。（サインインに使う Google アカウントが、Gmail Postmaster Tools にアクセスできることを確認してください。）

Claude / Cowork にインストールする（.mcpb）

.mcpb は Claude Desktop / Cowork 専用のパッケージ形式です。

1. 最新リリースから gmail-postmaster-tools.mcpb をダウンロードします。
2. Settings → Capabilities → install extension を開き、ファイルを選択します。
3. 入力を求められたら、Google OAuth Client ID と Client Secret を貼り付けます。
4. gpt_authenticate を 1 回実行すると、Google サインイン用にブラウザーが開きます。

他の MCP クライアント（Cursor、VS Code、Windsurf、…）での使用

これは標準的な stdio MCP サーバーです。ローカルの MCP サーバーを実行できるクライアントであれば、.mcpb は必要なく、そのまま使用できます。リポジトリをクローンまたはダウンロードし、クライアントで server/index.js を指定して、Google の認証情報を環境変数として渡します。

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）を編集します。

{
  "mcpServers": {
    "gmail-postmaster-tools": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-postmaster-tools-mcp/server/index.js"],
      "env": {
        "GPT_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "GPT_CLIENT_SECRET": "xxxxx"
      }
    }
  }
}

VS Code（.vscode/mcp.json）、Windsurf、Claude Desktop（手動設定）、およびほとんどの他のクライアントでは、同じ command + args + env の形式を使用します。異なるのは設定ファイルの場所だけです。他の環境変数によるオーバーライドについては、設定をご覧ください。

最初のツール呼び出し（または gpt_authenticate）で、Google へのサインインのためにブラウザーが開きます。127.0.0.1 へのループバックは、どのローカルデスクトップクライアントでも機能します。

リモート専用クライアント（例：Perplexity、ChatGPT コネクター）： これらのクライアントが受け付けるのはリモートの HTTPS MCP サーバー URL のみで、ローカルコマンドには対応していないため、この stdio ビルドを直接追加することはできません。使用するにはホスティングが必要です。それを提供するのが Postmaster+ です。

使用例

• 「Gmail Postmaster Tools にサインインして」 → gpt_authenticate
• 「Postmaster のドメインを一覧表示して」 → list_domains
• 「example.com は Gmail の送信者ルールに準拠していますか？」 → get_compliance_status { domain: "example.com" }
• 「過去 30 日間の example.com の迷惑メール率」 → query_domain_stats { domain: "example.com", start_date: "...", end_date: "...", metrics: ["SPAM_RATE"] }
• 「example.com の DKIM 認証成功率」 → query_domain_stats { domain: "example.com", metrics: [{ "standardMetric": "AUTH_SUCCESS_RATE", "filter": "auth_type=\"dkim\"" }] }

一部の指標にはフィルターが必要です：AUTH_SUCCESS_RATE（auth_type=spf|dkim|dmarc）、TLS_ENCRYPTION_RATE（traffic_direction=inbound|outbound）、DELIVERY_ERROR_RATE（error_type=... は任意）。SPAM_RATE には必要ありません。

認証の仕組み

OAuth 2.0 の認可コードフロー + PKCE を、http://127.0.0.1:<dynamic-port> へのループバックリダイレクトで使用します（デスクトップアプリ向けに Google が推奨するフローです）。サインイン時にサーバーは 127.0.0.1 で短時間だけ有効なリスナーを起動し、ブラウザーを開いてコードを受け取り、クライアントシークレットと PKCE 検証子を使ってトークンと交換します。

Google はデスクトップアプリでもクライアントシークレットを必須としているため、両方の値が必要です。トークンはお使いのマシン上の ~/.gmail-postmaster-mcp/tokens.json（0600）にのみ保存され、Git の追跡対象外です。

スコープ： デフォルトでは、サーバーは postmaster.traffic.readonly（指標 + コンプライアンス）と postmaster.domain（ドメインの一覧表示／取得）を要求します。スコープを絞りたい場合は、GPT_SCOPE 環境変数で上書きしてください（例：トラフィックのみにして、list_domains／get_domain を除外する）。

トークンの有効期間（重要）

公開ステータスが Testing の OAuth アプリ（上記のセットアップ手順で、検証を省略するために使用するモード）では、Google は 7 日後にリフレッシュトークンを失効させます。実際には、週に 1 回ほど gpt_authenticate を再実行する必要があります。サーバーはこれを適切に処理します。リフレッシュに失敗すると、ツール呼び出し時に再認証するよう通知されます。

毎週の再認証をなくすには、OAuth アプリの公開ステータスを In production に設定します（Google Auth Platform → Audience → Publish app）。postmaster（機密）スコープに関する注意事項：

• 本番環境、未検証 — リフレッシュトークンは 7 日後に失効しなくなります。それでも「Google hasn't verified this app」画面での操作は必要で、検証されるまでアプリのユーザー数は 100 人に制限されます。自分だけで使用する場合は、これが簡単な解決方法です。
• 検証済み — Google の OAuth 検証にアプリを申請すると、警告とユーザー数の上限をなくせます。アプリを広く配布する場合にのみ価値があります。

Configuration（環境変数による上書き）

変数	用途	デフォルト
GPT_CLIENT_ID	Google OAuth クライアント ID（必須）	—
GPT_CLIENT_SECRET	Google OAuth クライアントシークレット（必須）	—
GPT_SCOPE	スペース区切りの OAuth スコープ	traffic.readonly + domain
GPT_API_BASE	API ベース URL	https://gmailpostmastertools.googleapis.com/v2
GPT_TOKEN_DIR	トークンキャッシュディレクトリ	~/.gmail-postmaster-mcp
GPT_LOGIN_TIMEOUT_MS	サインインの待機時間	180000
GPT_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト	60000

ビルド

npx @anthropic-ai/mcpb validate manifest.json
npx @anthropic-ai/mcpb pack . gmail-postmaster-tools.mcpb

vX.Y.Z タグをプッシュすると、CI がパッケージを作成し、.mcpb を GitHub Release に添付して、MCP Registry に公開します。

依存関係がゼロである理由

Node.js の組み込み機能（http、https、crypto、readline）のみを使用するため、バンドルは小さく、サプライチェーンのリスクがなく、 npm install も不要です。

コントリビューション

CONTRIBUTING.md をご覧ください。

ライセンス

MIT © OptiPub

---

Google と提携または Google の承認を受けたものではありません。「Gmail」、「Google」、「Postmaster Tools」は Google LLC の商標です。