faithk7-gmail-mcp

Gmail API 向けの Model Context Protocol (MCP) サーバー実装です。メールの管理、送信、取得のための標準インターフェースを提供します。

機能

• メッセージ、スレッド、ラベル、下書き、設定を含む Gmail API の全機能に対応
• メールの送信、下書きの作成、管理に対応
• カスタマイズ可能な色と表示設定によるラベル管理
• 会話を管理するためのスレッド操作
• 不在時の自動返信、IMAP/POP、言語設定などの設定管理
• メールボックスの変更履歴の追跡
• Google Cloud 認証情報を使用した安全な OAuth2 認証

前提条件

依存関係

最も簡単にインストールするには、Node.js 18+をインストールしてください。ローカルでビルドする場合は、pnpmもインストールする必要があります。

Google Workspace のセットアップ

この MCP サーバーを実行するには、組織用の Google API クライアントを設定する必要があります。また、各ユーザーがスクリプトを実行して、それぞれの OAuth リフレッシュトークンを取得する必要があります。

Google API クライアントのセットアップ（組織ごとに 1 回）

1. Google Cloud Consoleにアクセスします。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. プロジェクトで Gmail API を有効にします。
4. 「認証情報」に移動し、OAuth 2.0 クライアント ID を作成します。クライアントの種類として「デスクトップアプリ」を選択します。
5. OAuth キーの JSON をダウンロードし、~/.gmail-mcp/gcp-oauth.keys.jsonとして保存します。⚠️ 注意：MacOS の Finder アプリで~/.gmail-mcp/を作成するには、まず隠しファイルを有効にする必要があります。
6. （任意）リモートサーバーのインストール（Smithery CLI の使用など）の場合は、このファイルに記載されているCLIENT_IDとCLIENT_SECRETを控えておきます。

クライアント OAuth（ユーザーごとに 1 回）

1. ユーザーに~/.gmail-mcp/gcp-oauth.keys.jsonを同じパスで自分のコンピューターにコピーしてもらいます。
2. npx @shinzolabs/gmail-mcp authを実行します。
3. ブラウザーウィンドウが開き、ユーザーはプロフィールを選択し、要求されたスコープを確認して、承認できます。
4. （任意）リモートサーバーのインストールの場合は、成功メッセージに記載されているファイルパス（デフォルトでは~/.gmail-mcp/credentials.json）を控えておきます。ユーザーのREFRESH_TOKENはこのファイルにあります。

クライアントの設定

MCP クライアントでサーバーを設定する方法はいくつかあります。ホスト型またはリモートサーバーをセットアップする場合は、Smithery API Keyを使用して Smithery の CLI を利用してください。ローカルにインストールする場合は、npxを使用するか、ソースからビルドしてください。各方法について、以下で説明します。

Smithery リモートサーバー（推奨）

MCP クライアントの config.json にリモートサーバーを追加するには、Smithery CLI から次のコマンドを実行します。

npx -y @smithery/cli install @shinzo-labs/gmail-mcp

プロンプトが表示されたら、CLIENT_ID、CLIENT_SECRET、REFRESH_TOKEN を入力します。

Smithery SDK

独自のエージェントアプリケーションを開発している場合は、こちらのボイラープレートコードを使用できます。

NPX ローカルインストール

npx を使用してサーバーをローカルにインストールするには、MCP クライアントの config.json に次の内容を追加します。

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}

ソースからビルド

1. リポジトリをダウンロードします。

git clone https://github.com/shinzo-labs/gmail-mcp.git

2. クローンしたリポジトリ内で、パッケージをインストールし、pnpm でビルドします。

pnpm i && pnpm build

3. MCP クライアントの config.json に次の内容を追加します。

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-mcp/dist/index.js"
      ]
    }
  }
}

設定変数

変数	説明	必須？	デフォルト
AUTH_SERVER_PORT	一時的な OAuth 認証サーバーのポート	いいえ	3000
CLIENT_ID	Google API クライアント ID（GMAIL_OAUTH_PATH にあります）	リモートサーバー接続時は必須	''
CLIENT_SECRET	Google API クライアントシークレット（GMAIL_OAUTH_PATH にあります）	リモートサーバー接続時は必須	''
GMAIL_CREDENTIALS_PATH	ユーザー認証情報ファイルのパス	いいえ	MCP_CONFIG_DIR/credentials.json
GMAIL_OAUTH_PATH	Google API クライアントファイルのパス	いいえ	MCP_CONFIG_DIR/gcp-oauth.keys.json
MCP_CONFIG_DIR	設定ファイルを保存するディレクトリ	いいえ	~/.gmail-mcp
REFRESH_TOKEN	OAuth リフレッシュトークン（GMAIL_CREDENTIALS_PATH にあります）	リモートサーバー接続時は必須	''
PORT	ストリーミング可能な HTTP トランスポート方式のポート	いいえ	3000
TELEMETRY_ENABLED	テレメトリを有効にする	いいえ	true

サポートされるエンドポイント

ユーザー管理

• get_profile：現在のユーザーの Gmail プロフィールを取得します
• stop_mail_watch：プッシュ通知の受信を停止します
• watch_mailbox：メールボックスの変更に関するプッシュ通知を設定します

メッセージ管理

メッセージの管理

• list_messages：任意のフィルター条件を指定してメッセージを一覧表示します
• get_message：特定のメッセージを取得します
• get_attachment：メッセージの添付ファイルを取得します
• modify_message：メッセージのラベルを変更します
• send_message：指定した宛先にメールメッセージを送信します
• delete_message：メッセージを完全に削除します
• trash_message：メッセージをごみ箱に移動します
• untrash_message：メッセージをごみ箱から戻します
• batch_modify_messages：複数のメッセージを変更します
• batch_delete_messages：複数のメッセージを削除します

ラベル管理

• list_labels：すべてのラベルを一覧表示します
• get_label：特定のラベルを取得します
• create_label：新しいラベルを作成します
• update_label：ラベルを更新します
• patch_label：ラベルを部分的に更新します
• delete_label：ラベルを削除します

スレッド管理

• list_threads：メールスレッドを一覧表示します
• get_thread：特定のスレッドを取得します
• modify_thread：スレッドのラベルを変更します
• trash_thread：スレッドをごみ箱に移動します
• untrash_thread：スレッドをごみ箱から戻します
• delete_thread：スレッドを削除します

下書きの管理

• list_drafts：ユーザーのメールボックスにある下書きを一覧表示します
• get_draft：IDを指定して下書きを取得します
• create_draft：Gmailでメールの下書きを作成します
• update_draft：下書きの内容を置き換えます
• delete_draft：下書きを削除します
• send_draft：既存の下書きを送信します

設定の管理

自動転送

• get_auto_forwarding：自動転送の設定を取得します
• update_auto_forwarding：自動転送の設定を更新します

IMAP の設定

• get_imap：IMAP の設定を取得します
• update_imap：IMAP の設定を更新します

POP の設定

• get_pop：POP の設定を取得します
• update_pop：POP の設定を更新します

不在通知

• get_vacation：不在通知の設定を取得します
• update_vacation：不在通知を更新します

言語の設定

• get_language：言語の設定を取得します
• update_language：言語の設定を更新します

委任者

• list_delegates：アカウントの委任者を一覧表示します
• get_delegate：特定の委任者を取得します
• add_delegate：委任者を追加します
• remove_delegate：委任者を削除します

フィルター

• list_filters：メールフィルターを一覧表示します
• get_filter：特定のフィルターを取得します
• create_filter：新しいフィルターを作成します
• delete_filter：フィルターを削除します

転送先アドレス

• list_forwarding_addresses：転送先アドレスを一覧表示します
• get_forwarding_address：特定の転送先アドレスを取得します
• create_forwarding_address：転送先アドレスを作成します
• delete_forwarding_address：転送先アドレスを削除します

送信元設定

• list_send_as：送信元エイリアスを一覧表示します
• get_send_as：特定の送信元エイリアスを取得します
• create_send_as：送信元エイリアスを作成します
• update_send_as：送信元エイリアスを更新します
• patch_send_as：送信元エイリアスを部分的に更新します
• verify_send_as：確認メールを送信します
• delete_send_as：送信元エイリアスを削除します

S/MIME の設定

• list_smime_info：S/MIME 設定を一覧表示します
• get_smime_info：特定の S/MIME 設定を取得します
• insert_smime_info：新しい S/MIME 設定をアップロードします
• set_default_smime_info：デフォルトの S/MIME 設定を設定します
• delete_smime_info：S/MIME 設定を削除します

コントリビューション

コントリビューションを歓迎します。イシュー、コントリビューション、連絡先に関するガイドラインは、CONTRIBUTING.md をお読みください。

データ収集とプライバシー

Shinzo Labs は、製品やサービスの改善に役立てるため、このサーバーから限定的な匿名テレメトリーを収集します。このプロセスで個人を特定できる情報が収集されることはありません。収集するデータの種類と、このテレメトリーをオプトアウトする方法について詳しくは、プライバシーポリシーをご確認ください。

ライセンス

MIT