Skip to main content
Glama
Gmail MCP Gateway

Gmail MCP Gateway

by systheno

Gmail MCP Gateway

AIエージェントに複数のGmailアカウントへの完全な読み取りおよび整理アクセスを提供するMCPサーバー。メールの送信、ゴミ箱への移動、削除は一切できません。

                     Gmail MCP Gateway

        ALLOWED                        FORBIDDEN
        ───────                        ─────────
        Search                         Send
        Read messages                  Send draft
        Read threads                   Trash
        Read attachments               Delete
        Create drafts                  Mark spam
        Edit drafts                    Gmail settings
        Archive                        Forwarding rules
        Read / unread                  Arbitrary API calls
        Labels

この保証は、クライアントへの指示ではなく、アプリケーションコードによって強制されます。バグがある、侵害された、またはプロンプトインジェクションを受けたMCPクライアントは、このゲートウェイを介してメールを送信できません。それを可能にするコードパスが存在しないためです。


目次


Related MCP server: Gmail MCP Server

クイックスタート

Python 3.11以上が必要です。5ステップ、約10分(ほとんどはGoogleコンソールでの作業です)。

1. インストール

git clone <this-repo> gmail-mcp-gateway
cd gmail-mcp-gateway
uv sync                                  # or: python -m venv .venv && .venv/bin/pip install -e .
.venv/bin/gmail-mcp-gateway --version

必要に応じてPATHに追加すると、以下の例がより自然に読めるようになります。

export PATH="$PWD/.venv/bin:$PATH"

2. Google OAuthクライアントの作成

一度だけの無料の作業で、後で追加するすべてのアカウントで共有されます。

  1. https://console.cloud.google.com/ でプロジェクトを作成します。

  2. APIとサービス → ライブラリ → Gmail API を有効にします。

  3. APIとサービス → OAuth同意画面 → 外部、必須項目を入力し、テストユーザーに自分のGoogleアカウントを追加します。

  4. アプリを公開します(自分だけがユーザーの場合、まだ審査は必要ありません)。これをスキップすると、アプリは「テスト中」のままになり、Googleは7日後にリフレッシュトークンを期限切れにし、毎週再承認が必要になります。

  5. 認証情報 → 認証情報を作成 → OAuthクライアントID → デスクトップアプリ → JSONをダウンロード。

ここでスコープを選択する必要はありません。ゲートウェイは認証時に必要なものだけを要求し、Gmail以外のものは要求しません。

3. OAuthクライアントのインストール

install -Dm600 ~/Downloads/client_secret_*.json \
  ~/.local/share/gmail-mcp-gateway/secrets/oauth_client.json

手動で配置する必要があるファイルはこれだけです。暗号化キーは初回実行時に生成されます。

4. アカウントの認証

gmail-mcp-gateway accounts add personal

ブラウザが開きます。要求された権限を承認し、すべてのチェックボックスをオンにしたままにします(権限が拒否された場合、ゲートウェイは中途半端に動作するのではなく、明確に失敗します)。リフレッシュトークンは暗号化されて保存され、以降ゲートウェイは無人で動作します。

好きなだけ追加できます。それぞれに独自の同意、リフレッシュトークン、暗号化キー、レート制限バケット、監査証跡が与えられます。

gmail-mcp-gateway accounts add work
gmail-mcp-gateway accounts add newsletters --read-only   # Google itself refuses writes

5. 確認

gmail-mcp-gateway health          # exit 0 = ready, 2 = something is wrong
[ok  ] directories      config=/home/you/.config/gmail-mcp-gateway ...
[ok  ] database         /home/you/.local/share/gmail-mcp-gateway/gateway.db
[ok  ] master_key       loaded
[ok  ] oauth_client     configured
[ok  ] accounts         1/1 authorized

gmail-mcp-gateway 1.0.0: healthy

その後、MCPクライアントを接続します(MCPクライアントの接続を参照)。または、先に試してみることもできます。

uv run python scripts/try-it.py --account personal

環境変数

通常のローカルインストールでは、これらは一切必要ありません。 上記のクイックスタートでは環境変数を設定していません。デフォルトでは、設定は~/.configに、データとシークレットは~/.local/shareに配置され、暗号化キーは自動生成されます。

これらは、コンテナ、systemdユニット、シークレットマネージャーなど、ディスク上のファイルが適切でない場所のために存在します。

変数

必須?

デフォルト

目的

GMAIL_MCP_OAUTH_CLIENT_ID

いいえ¹

—

Google OAuthクライアントID

GMAIL_MCP_OAUTH_CLIENT_SECRET

いいえ¹

—

Google OAuthクライアントシークレット

GMAIL_MCP_MASTER_KEY

いいえ²

自動生成

base64 32バイトの認証情報暗号化キー

GMAIL_MCP_CONFIG_DIR

いいえ

~/.config/gmail-mcp-gateway

config.toml; 機密情報なし

GMAIL_MCP_DATA_DIR

いいえ

~/.local/share/gmail-mcp-gateway

gateway.db, attachments/

GMAIL_MCP_SECRETS_DIR

いいえ

<data>/secrets

キー、OAuthクライアント、認証情報

GMAIL_MCP_HTTP_HOST

いいえ

127.0.0.1

HTTPバインドアドレス

GMAIL_MCP_HTTP_PORT

いいえ

8765

HTTPバインドポート

GMAIL_MCP_HTTP_ENABLED

いいえ

false

設定によるHTTPトランスポートの有効化

GMAIL_MCP_ALLOW_REMOTE_BIND

いいえ

false

ループバック以外のバインドを許可

GMAIL_MCP_LOG_LEVEL

いいえ

INFO

DEBUG…CRITICAL

¹ secrets/oauth_client.jsonの代替。ファイルまたはペアのいずれかを提供します。 ² 未設定の場合、ゲートウェイは初回実行時にsecrets/master.key(モード0600)を作成します。

環境変数はconfig.tomlを上書きし、config.tomlはデフォルトを上書きします。

各値の生成

OAuthクライアントIDとシークレット — クイックスタートのステップ2でダウンロードしたJSONから取得します。ファイルの代わりに環境変数を使用する場合:

jq -r '.installed.client_id'     ~/Downloads/client_secret_*.json
jq -r '.installed.client_secret' ~/Downloads/client_secret_*.json

マスターキー — 32バイトのランダムデータをbase64エンコード:

openssl rand -base64 32
# or, without openssl:
python3 -c "import base64,secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"

このキーは保存されたリフレッシュトークンを復号化します。アカウントを追加した後にこれを変更すると、認証情報が読み取り不能になり、すべてのアカウントでaccounts reauthが必要になります。データディレクトリをバックアップする場所に、このキーもバックアップしてください。

ゲートウェイベアラートークン — 環境変数ではありません。これはMCPクライアントがHTTPトランスポート経由で送信するもので、Googleの認証情報とは無関係です。CLIがこれを生成し、SHA-256ハッシュのみを保存します。

gmail-mcp-gateway token create my-agent

平文は一度だけ出力され、クライアントの設定に記述されます。

envファイルの使用

ゲートウェイは.envを自動的に読み取りません。セキュリティツールが起動されたディレクトリから黙ってシークレットを吸収するべきではないからです。.env.exampleをコピーします(すべての変数が文書化されています)。明示的に読み込んでください。

cp .env.example .env       # already covered by .gitignore
$EDITOR .env
set -a && source .env && set +a
gmail-mcp-gateway health

systemdはEnvironmentFile=を使用します。Docker Composeはenv_file:を使用します。


実行方法

stdio — 通常の選択肢

クライアントがゲートウェイを子プロセスとして起動し、パイプ経由で通信します。ポートもトークンもネットワーク公開もありません。Googleの認証情報はゲートウェイプロセス内に留まり、クライアントはツール呼び出しのみを認識します。

gmail-mcp-gateway serve --transport stdio

手動で実行するとハングしているように見えますが、それは正しい動作です。stdinからのJSON-RPCを待機しています。通常はMCPクライアントが自動的に起動します。

Streamable HTTP — スタンドアロンサービス

長時間稼働するサービスや、プロセスを生成できないクライアント向け。

gmail-mcp-gateway token create my-agent          # once; save the printed token
gmail-mcp-gateway serve --transport http --host 127.0.0.1 --port 8765

エンドポイントはループバックにバインドされ、ベアラートークンを必要とし、DNSリバインディング保護が有効です。GET /healthzは認証不要で、生存確認のみを報告します。

ループバック以外のアドレスにバインドするにはGMAIL_MCP_ALLOW_REMOTE_BIND=trueが必要で、インターネット経路可能なアドレスはそれでも拒否されます。リモートクライアントの場合はトンネルを使用します。

ssh -L 8765:127.0.0.1:8765 gateway-host

systemd

deploy/gmail-mcp-gateway.serviceは、専用のシステムユーザーとして、強化されたサンドボックス(ProtectSystem=strict、空のCapabilityBoundingSet、seccompフィルター、データディレクトリに対するNoExecPaths)で実行されます。インストール手順はユニットのヘッダーに記載されています。サービスユーザーとして、起動前に一度だけインタラクティブにアカウントを認証します。

Docker

deploy/Dockerfileとdeploy/docker-compose.ymlは、非rootかつ読み取り専用で実行され、すべてのケーパビリティが削除され、ポートはループバックのみに公開されます。イメージには認証情報は含まれず、/secretsボリュームに保存されます。

docker compose -f deploy/docker-compose.yml up -d

一度だけ必要な認証シーケンス(OAuthクライアントの配置、リダイレクトポートを公開した同意フローの実行、トークンの生成)は、composeファイルのヘッダーコメントに記載されています。


MCPクライアントの接続

stdio

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/gmail-mcp-gateway/.venv/bin/gmail-mcp-gateway",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add gmail -- /absolute/path/to/.venv/bin/gmail-mcp-gateway serve --transport stdio

HTTP

{
  "mcpServers": {
    "gmail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer <token from `token create`>" }
    }
  }
}

クライアントはGoogleの認証情報ファイルをマウントしたりアクセスしたりすることはありません。stdioではクライアントはパイプと通信し、HTTPではGoogleの認証情報とは無関係のゲートウェイトークンを保持します。


ツールリファレンス

すべてのツールはaccountエイリアスを必要とします。デフォルトのアカウントはありません。変更を行うツールは、冪等性のためにオプションのclient_request_idを受け入れます。同じIDと引数で呼び出しを繰り返すと、2回目の動作は行われず、最初の結果が返されます。

ツール

機能

accounts_list

エイリアス、アドレス、ステータス、許可された機能。認証情報は含まれません。

accounts_status

アカウントごとのライブ認証チェックと、メールボックスの合計数。

gmail_search

Gmail検索構文。detailはids、metadata、fullから選択。ページネーション対応。

gmail_get_message

1件のメッセージ:送信者、To、Cc、Bcc、件名、タイムスタンプ、ラベル、既読状態、本文、添付ファイル一覧。

gmail_get_thread

会話全体を時系列順に、参加者情報付きで取得。

gmail_attachments_list

添付ファイルの一覧。ダウンロードは行いません。

gmail_attachments_get

バイトデータを取得。小さい場合はインラインbase64、それ以外はゲートウェイ自身のディレクトリに書き込み。

gmail_labels_list

すべてのラベルとそのカウント、およびゲートウェイが各ラベルを変更するかどうか。

gmail_labels_add

IDまたは名前でラベルを適用。TRASHとSPAMは拒否。

gmail_labels_remove

IDまたは名前でラベルを削除。TRASHとSPAMは拒否。

gmail_archive

INBOXを削除。メールは「すべてのメール」に残り、元に戻せます。

gmail_mark_read

UNREADを削除。

gmail_mark_unread

UNREADを追加。

gmail_drafts_list

保存された下書きの一覧(受信者、件名、スニペット付き)。

gmail_drafts_get

1件の下書きを完全な形で取得。

gmail_drafts_create

新しいプレーンテキストの下書きを作成。保存のみ、送信はされません。

gmail_drafts_reply

既存のスレッド内での返信下書きを作成。In-Reply-To、References、件名、threadIdが正しく設定される。

gmail_drafts_update

下書きを編集。省略されたフィールドはそのまま保持され、スレッド情報は維持される。

変更操作は個別のメッセージまたはスレッド、およびバッチ(デフォルト上限100 ID)に対して機能します。ラベルはID(Label_7)または表示名(Receipts)で指定できます。

読み取りと書き込みは、重要な点で非対称に扱われます。gmail_searchはTRASHでのフィルタリングやinclude_spam_trashの設定を問題なく行います。これは既存のものを検査する読み取りだからです。それらのラベルを適用することは拒否されます。それはメールをゴミ箱に移動したりスパムとして報告したりすることになるからです。

エラー

失敗は、isError: trueと、テキストブロックと構造化コンテンツの両方に構造化されたペイロードを含むMCPツールエラーとして返されます。

{"error": {
  "code": "forbidden_label",
  "message": "refusing to add label 'TRASH': moving messages to Trash is a forbidden capability of this gateway",
  "retryable": false
}}

コードには、invalid_input、unknown_account、not_found、too_large、batch_too_large、rate_limited、forbidden_operation、forbidden_label、account_read_only、needs_reauth、upstream_rate_limited、upstream_unavailable、network_error、timeout、internal_errorが含まれます。内部例外はサーバー側でログに記録され、単にinternal_errorとして報告されます。クライアントがトレースバックや内部パスを受け取ることはありません。


管理

gmail-mcp-gateway accounts list
gmail-mcp-gateway accounts status               # live Gmail check per account
gmail-mcp-gateway accounts auth <alias>
gmail-mcp-gateway accounts reauth <alias>       # after a revoked or expired grant
gmail-mcp-gateway accounts remove <alias> --yes # revokes at Google, deletes locally

gmail-mcp-gateway token create <name>
gmail-mcp-gateway token list
gmail-mcp-gateway token revoke <name>

gmail-mcp-gateway audit --limit 50              # recent state-changing operations
gmail-mcp-gateway audit --account work --since-hours 24
gmail-mcp-gateway audit --outcome denied --json

gmail-mcp-gateway prune                         # expired audit rows, dedup keys, attachments
gmail-mcp-gateway health --json

ヘッドレスホストでは、リダイレクトポートを転送して認可します。

# on the server
gmail-mcp-gateway accounts add work --no-browser --port 8899
# on your laptop
ssh -L 8899:127.0.0.1:8899 server
# then open the printed URL locally

監査ログには、成功・失敗・拒否を問わず、アカウント、タイムスタンプ、操作、影響を受けたID、結果、エラーコード、所要時間、呼び出し元プリンシパルが記録されます。トークン、メッセージ本文、件名、添付ファイルの内容は決して記録されません。管理はCLIのみです。侵害されたMCPクライアントでは、アカウントの追加、同意フローのトリガー、トークンの発行、監査ログの読み取りはできません。

ディレクトリ構成

設定、データ、シークレットは分離されており、それぞれ個別に上書き可能なため、それぞれ異なるバックエンドストアを使用できます。

役割

変数

デフォルト

内容

設定

GMAIL_MCP_CONFIG_DIR

~/.config/gmail-mcp-gateway

config.toml — 秘密情報は含まれません

データ

GMAIL_MCP_DATA_DIR

~/.local/share/gmail-mcp-gateway

gateway.db, attachments/

シークレット

GMAIL_MCP_SECRETS_DIR

<data>/secrets

master.key, oauth_client.json, credentials/, gateway_tokens.json

config.toml はオプションです。すべてのキー(バッチ上限、ページサイズ、本文と添付ファイルの予算、レート制限、リトライポリシー、冪等性ウィンドウ)とそのデフォルト値については、deploy/config.example.toml を参照してください。


境界がどのように強制されるか

4つの独立した層。それぞれ単独で送信をブロックします。メッセージが外部に出るには、4つすべてが失敗する必要があります。

1. ツールサーフェス。 18個のツールが存在します。gmail_send、gmail_trash、gmail_raw_request、またはURL、パス、HTTPメソッド、エンドポイント名を受け付けるツールはありません。汎用のGmailプロキシは、クライアントが到達できません。なぜなら、それが書かれていないからです。mcpsrv/server.py

2. エンドポイント許可リスト。 GmailへのすべてのHTTPリクエストは、14個の Endpoint 定数のいずれかを指定する必要があります。users.messages.send、users.drafts.send、users.messages.trash、users.messages.delete、および users.settings 以下のすべては単に存在しません。パスパラメータは厳格なIDパターンに対して検証され、空の安全セットでパーセントエンコードされるため、どの値も / を導入して別のエンドポイントに到達することはできません。拒否リストは、リクエストが送信される直前に、解決されたメソッドとパスを、それがどのように構築されたかとは独立して再チェックします。DELETE と PATCH はまったく発行できません。gmail/allowlist.py

3. ラベルポリシー。 これにより、許可リストが残したバックドアが閉じられます。users.messages.modify は許可されています(アーカイブや既読状態の動作に必要)が、Gmailは TRASH と SPAM を通常のラベルとして扱うため、これらを適用するとメッセージがゴミ箱に入れられるかスパムとして報告されます。ミューテーション内のすべてのラベルIDは、大文字小文字を区別せずに双方向でチェックされ、組み立てられたリクエスト本文は送信前に再度チェックされます。gmail/labels.py

4. OAuthスコープ。 アカウントは gmail.modify のみで認可され、それ以外はありません。このスコープではメッセージを完全に削除できず(messages.delete には https://mail.google.com/ が必要)、Gmailの設定には一切触れられないため、転送ルール、フィルタ、POP/IMAP設定、完全削除はGoogleの認可レイヤーで不可能となり、単にここでブロックされるわけではありません。Googleは、送信なしで下書き作成を許可するスコープを公開していないため、送信はレイヤー1〜2でブロックされます。--read-only で追加されたアカウントは gmail.readonly を取得し、Google自体がすべての書き込みを拒否します。


セキュリティモデル

メールコンテンツは信頼されていません。 本文、件名、送信者名、添付ファイル名は第三者によって書かれ、それを読むモデルに向けた指示を含む可能性があります。ゲートウェイはすべての読み取り結果に content_is_untrusted: true をマークし、サーバー指示はクライアントにメールをデータとして扱い、指示として扱わないように伝えます。より有用なことに、注入された指示が要求するであろう機能は存在しません。

HTMLは決して実行されず、マークアップとして返されることもありません。 <script>、<style>、<iframe> および類似の要素はその内容ごと破棄され、他のすべてのタグは削除されます。結果はプレーンテキストです。

不可視のUnicodeは除去されます。 ゼロ幅文字、双方向オーバーライド、Unicodeタグ文字により、攻撃者は人間に別のものを表示し、LLMには別のものを読ませることができます。これらは削除され、その数は removed_hidden_characters として報告されます。

添付ファイルは保存され、開かれることはありません。 ゲートウェイは添付ファイルの内容を解析、レンダリング、実行しません。クライアントはファイル名を提案できますが、パスは決して提案できません。保存先は常に <attachments_dir>/<account>/<message_id>/<sanitized-name> であり、解決されてコンテナ内にあるか再チェックされ、O_NOFOLLOW でモード0600で書き込まれます。

認証情報はクライアントに決して到達しません。 リフレッシュトークン、アクセストークン、OAuthクライアントシークレットはゲートウェイプロセス内にのみ存在します。各アカウントの認証情報は、アカウントごとに派生した鍵(HKDF-SHA256(master, "…account:<id>"))でAES-256-GCMにより封印され、アカウントIDが関連データとして使用されます。そのため、あるアカウントの鍵で別のアカウントを開くことはできず、アカウント間で移動された認証情報ファイルは復号に失敗します。ファイルは0700ディレクトリ内で0600のパーミッションを持ち、ゲートウェイはグループまたはワールドから読み取り可能な鍵を拒否します。

正直なスコープ: 保存時の暗号化は、バックアップ、紛失したコピー、ディスクイメージから保護します。ゲートウェイのユーザーとしてコードを実行している攻撃者からは防御しません。その攻撃者はマスターキーを読み取ることができます。ファイルシステムのパーミッションが依然として主要な境界です。

ログは秘密を漏洩しません。 すべてのログレコードは、Googleのアクセストークンやリフレッシュトークン、クライアントシークレット、Bearerヘッダー、JWT、認証情報名のフィールドのように見えるものを、メッセージ、引数、例外テキスト内で書き換えるフィルターを通過します。stdioでは、stdoutがMCPワイヤであるため、ログはstderrに送られます。

入力は検証されます。 下書きの受信者は、厳格なパターンに一致するベアアドレスでなければならず、ヘッダー値にCR、LF、NULが含まれている場合はヘッダーインジェクションの試みとして拒否されます。下書きは型付きフィールドから組み立てられます。ゲートウェイはクライアントから生のRFC 5322を受け付けることはありません。バッチ、ページサイズ、本文長、添付ファイルサイズ、受信者数はすべて上限があり、アカウントごとのトークンバケットはキューイングではなく retry_after_seconds ヒントで迅速に失敗します。

これが保護しないもの

  • ゲートウェイユーザーとしてコードを実行できるオペレーター。

  • 許可された機能を悪用する正当なクライアント(例:大量アーカイブ、誤解を招く下書きの作成)。アーカイブとラベル付けは元に戻せ、監査されます。下書きは送信に人間の操作を必要とします。

  • Google側の侵害や悪意のあるOAuthクライアント設定。

  • TLSなしでHTTPトランスポートを公開した場合のトラフィック傍受。ループバックで維持するか、TLS終端プロキシを前面に配置してください。


信頼性

  • トークンリフレッシュ: 自動。アカウントごとのロックにより、同時呼び出しは1回だけリフレッシュします。401 は正確に1回のリフレッシュとリトライをトリガーします。

  • リフレッシュ失敗: invalid_grant はアカウントを needs_reauth とマークし、修正するCLIコマンドを指定した構造化エラーを返します。

  • レート制限と5xx: 完全なジッターを伴う指数バックオフ。Retry-After を尊重し、max_attempts まで。

  • ネットワーク障害とタイムアウト: リトライ後、内部詳細なしで network_error または timeout として報告。

  • ページネーション: next_page_token はクライアントに返されるため、カーソル状態はサーバーに残りません。

  • 重複リクエスト: client_request_id により、24時間の間、繰り返しを抑制します。同時の繰り返しはプロセス内で直列化されます。異なる引数で同じIDを再利用するとエラーになり、黙って間違った結果を返すことはありません。

  • バックプレッシャー: Gmail呼び出しは設定可能な同時実行セマフォを共有し、各アカウントは独立したトークンバケットを持ちます。そのため、大規模な検索やビジーなアカウントが無制限の上流同時実行を生み出すことはありません。

スケーリングとデプロイメントトポロジ

特定のデータおよびシークレットディレクトリに対して、1つのゲートウェイプロセスを実行します。SQLiteの状態、認証情報ファイル、トークンリフレッシュロック、進行中の冪等性調整は意図的にローカルです。同じボリュームを指す複数のレプリカは、安全なアクティブ-アクティブ運用を提供しません。

大規模なインストールでは、アカウントを独立したゲートウェイインスタンスにシャーディングし、それぞれに独自の設定、データ、シークレット、ベアラートークン、ループバックポートを持たせます。これにより、障害、レート制限、監査証跡、認証情報が分離され、各インスタンスが同時クライアントにサービスを提供できるようになります。limits.max_concurrency は、Gmailクォータ使用量とホスト容量を確認した後にのみ増やしてください。デフォルトの8は控えめです。クライアントが1つの共有ネットワークアドレスを必要とする場合は、TLS認証されたルーティングレイヤーを前面に配置し、各アカウントエイリアスを自身のインスタンスにルーティングします。

同じアカウントに対するアクティブ-アクティブレプリカは、SQLiteとローカルの認証情報/冪等性状態を調整された外部ストアに置き換える必要があります。これは現在のゲートウェイのセキュリティモデルの範囲外です。単にワーカーを追加したりボリュームを共有したりしてスケールしないでください。


テスト

uv sync --all-extras
uv run pytest -q                                    # 334 tests, no Google account needed
uv run pytest tests/test_security_boundary.py -v    # just the guarantee

test_security_boundary.py は、モックGmailを通じてすべてのサポート対象操作を駆動し、禁止されたURLがリクエストされた場合に失敗し、その後、利用可能なすべてのルートでゴミ箱、スパム、送信を試みます。

アカウントが認可されたら、実際のメールボックスに対してテストします。スクリプトはMCPクライアントとまったく同じようにstdio経由で接続し、読み取り専用ツアーを実行した後、禁止された操作が拒否されることを確認します。

uv run python scripts/try-it.py --account personal
uv run python scripts/try-it.py --account personal --draft    # also drafts a reply
uv run python scripts/try-it.py --account personal --archive  # archive round trip

ミューテーションフラグを渡さない限り読み取り専用であり、行うすべてのミューテーションは元に戻せます。作成された下書きは、あなたが削除する必要があります。ゲートウェイは削除できません。

インタラクティブに試すには:

npx @modelcontextprotocol/inspector .venv/bin/gmail-mcp-gateway serve --transport stdio

レイアウト

src/gmail_mcp_gateway/
├── mcpsrv/server.py      the tool surface — the complete client-facing API
├── mcpsrv/http.py        Streamable HTTP transport, bearer auth, bind safety
├── service.py            the supported operations, and nothing else
├── gmail/allowlist.py    the endpoint allowlist  ← security boundary
├── gmail/labels.py       label policy (blocks TRASH/SPAM)  ← security boundary
├── gmail/client.py       the only code that talks to Gmail
├── gmail/parse.py        MIME → structured data, sanitization
├── gmail/compose.py      draft assembly from typed fields
├── security/             validation, rate limiting, path confinement
├── auth/oauth.py         OAuth 2.0 + PKCE, refresh, revoke
├── accounts.py           account registry
├── crypto.py             envelope encryption for credentials
├── audit.py              audit log
└── cli.py                administration

サポート対象の操作を追加するということは、allowlist.py の Endpoint、service.py のメソッド、mcpsrv/server.py のツール、EXPOSED_TOOLS のエントリ、そしてテストを意味します。EXPOSED_TOOLS と FORBIDDEN_TOOLS は実行中のサーバーに対してアサートされるため、ツールを宣言せずに追加したり、禁止されたツールを追加したりすると、スイートは失敗します。ゲートウェイをGmailに集中させてください。別のGoogle製品は、ここでスコープを広げるのではなく、別のMCPサービスに属します。


トラブルシューティング

no OAuth client configured — クイックスタートのステップ3。secrets/oauth_client.json(モード0600)を配置するか、GMAIL_MCP_OAUTH_CLIENT_ID と GMAIL_MCP_OAUTH_CLIENT_SECRET を設定してください。

Google did not return a refresh token — このアプリを以前に認可しています。https://myaccount.google.com/permissions でアクセスを削除し、accounts auth <alias> を再度実行してください。

consent screen did not grant every required permission — 許可ボックスがチェックされていません。認可を再実行し、すべてチェックしたままにしてください。ゲートウェイは、中途半端に動作するアカウントを残すのではなく、意図的にここで失敗します。

アカウントが毎週 needs_reauth になる — OAuthアプリがまだ「テスト中」であり、Googleは7日後にリフレッシュトークンを期限切れにします。公開してください(クイックスタートのステップ2.4)。

stored credential failed authentication — GMAIL_MCP_MASTER_KEY が変更されたか、キーファイルが置き換えられました。元のキーを復元するか、各アカウントに対して accounts reauth <alias> を実行してください。

<file> is accessible to other users — ゲートウェイはグループまたはワールドから読み取り可能なシークレットを拒否します。指定されたファイルを chmod 600 してください。

refusing to bind …: it is not a loopback address — 意図的です。127.0.0.1にバインドしてSSHトンネルを使用するか、本当に信頼できるプライベートインターフェースである場合は GMAIL_MCP_ALLOW_REMOTE_BIND=true を設定してください。インターネット経路指定可能なアドレスは、設定に関わらず拒否されます。

serve --transport stdio がハングしているように見える — 正しい動作です。stdinでJSON-RPCを待機しています。MCPクライアントに起動させるか、scripts/try-it.py を使用してください。

メールボックスに何か変更があったので、その内容を知りたい — gmail-mcp-gateway audit --limit 50. すべての状態変更がここにあります。拒否も含まれます。

ライセンス

MIT

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Read-only MCP server for IMAP email access, enabling AI agents to read, search, and monitor email without sending or deleting messages.
    13 npm
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    MCP server that gives an AI assistant simultaneous access to multiple Gmail accounts with per-account read-only, draft, or send tiers, two-phase write confirmation, and safeguards for handling untrusted email content.
    10
    8 npm
    1
    MIT