Gmail 自動認証 MCP サーバー
Claude Desktop に Gmail を統合するための、自動認証をサポートするモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、AI アシスタントが自然言語によるインタラクションを通じて Gmail を管理できるようになります。
特徴
- 件名、内容、添付ファイル、受信者を指定してメールを送信する
- 件名とメール本文で国際文字を完全サポート
- 高度な MIME 構造処理を使用して ID で電子メール メッセージを読み取る
- メールの添付ファイル情報（ファイル名、種類、サイズ）を表示する
- さまざまな条件（件名、送信者、日付範囲）でメールを検索します
- ラベルの作成、更新、削除、一覧表示が可能な包括的なラベル管理
- 利用可能なすべての Gmail ラベル（システムおよびユーザー定義）を一覧表示します
- 受信トレイ、送信済み、またはカスタムラベル内のメールを一覧表示する
- メールを既読/未読としてマークする
- メールを別のラベル/フォルダに移動する
- メールを削除する
- 複数のメールを一度に効率的に処理するためのバッチ操作
- Gmail APIとの完全な統合
- 自動ブラウザ起動によるシンプルなOAuth2認証フロー
- デスクトップとWebアプリケーションの両方の資格情報のサポート
- 利便性のためのグローバル認証情報ストレージ
インストールと認証
Smithery経由でインストール
Smithery経由で Claude Desktop 用の Gmail AutoAuth を自動的にインストールするには:
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
手動でインストールする
- Google Cloud プロジェクトを作成し、認証情報を取得します。a. Google Cloud プロジェクトを作成します。
b. OAuth 2.0 認証情報を作成する:
- 「APIとサービス」>「認証情報」に移動します
- 「認証情報を作成」>「OAuthクライアントID」をクリックします
- アプリケーションの種類として「デスクトップアプリ」または「Webアプリケーション」を選択します
- 名前を付けて「作成」をクリックします
- Webアプリケーションの場合、承認されたリダイレクトURIに
http://localhost:3000/oauth2callbackを追加します。 - クライアントのOAuthキーのJSONファイルをダウンロードします
- キーファイルの名前を
gcp-oauth.keys.jsonに変更します。
- 実行認証:認証には 2 つの方法があります:a. グローバル認証（推奨）:
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth
- 現在のディレクトリまたは
~/.gmail-mcp/でgcp-oauth.keys.jsonを探します。 - 現在のディレクトリで見つかった場合は、
~/.gmail-mcp/にコピーします。 - Google認証用のデフォルトのブラウザを開きます
- 資格情報を
~/.gmail-mcp/credentials.jsonとして保存します。
注記：
- 認証が成功すると、認証情報は
~/.gmail-mcp/にグローバルに保存され、どのディレクトリからでも使用できるようになります。 - デスクトップ アプリと Web アプリケーションの両方の資格情報がサポートされています
- Webアプリケーションの認証情報の場合は、承認されたリダイレクトURIに
http://localhost:3000/oauth2callbackを追加してください。
- Claude Desktop で設定:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
Docker サポート
Docker を使用する場合:
- 認証:
docker run -i --rm \
--mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
-v mcp-gmail:/gmail-server \
-e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
-e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
-p 3000:3000 \
mcp/gmail auth
- 使用法：
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"mcp-gmail:/gmail-server",
"-e",
"GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
"mcp/gmail"
]
}
}
}
クラウドサーバー認証
クラウド サーバー環境 (n8n など) では、認証時にカスタム コールバック URL を指定できます。
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
クラウド環境のセットアップ手順
- リバースプロキシを構成する:
- 認証用のポートを公開するようにn8nコンテナを設定する
- リバースプロキシを設定して、ドメイン（例：
gmail.gongrzhe.com ）からのトラフィックをこのポートに転送します。
- DNS 構成:
- DNS設定にAレコードを追加して、ドメインをクラウドサーバーのIPアドレスに解決します。
- Google Cloud Platform のセットアップ:
- Google Cloud Console で、カスタム ドメイン コールバック URL（例:
https://gmail.gongrzhe.com/oauth2callback ）を承認済みリダイレクト URI リストに追加します。
- 実行認証:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
- アプリケーションで構成します:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
このアプローチにより、コンテナ化されたアプリケーションやクラウド サーバーなど、localhost にアクセスできない環境でも認証フローが適切に機能するようになります。
利用可能なツール
サーバーは、Claude Desktop を通じて使用できる次のツールを提供します。
1. メールを送信する ( send_email )
新しいメールをすぐに送信します。
{
"to": ["recipient@example.com"],
"subject": "Meeting Tomorrow",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"]
}
2. 下書きメール（ draft_email ）
電子メールを送信せずに下書きを作成します。
{
"to": ["recipient@example.com"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["manager@example.com"]
}
3. メールを読む ( read_email )
特定の電子メールの内容をその ID で取得します。
{
"messageId": "182ab45cd67ef"
}
4. メールを検索する（ search_emails ）
Gmail 検索構文を使用してメールを検索します。
{
"query": "from:sender@example.com after:2024/01/01 has:attachment",
"maxResults": 10
}
5. メールの変更 ( modify_email )
電子メールにラベルを追加または削除します (別のフォルダーに移動、アーカイブなど)。
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
6. メールを削除する（ delete_email ）
電子メールを完全に削除します。
{
"messageId": "182ab45cd67ef"
}
7. メールラベルの一覧表示（ list_email_labels ）
利用可能なすべての Gmail ラベルを取得します。
8. ラベルを作成する ( create_label )
新しい Gmail ラベルを作成します。
{
"name": "Important Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
9. ラベルを更新する ( update_label )
既存の Gmail ラベルを更新します。
{
"id": "Label_1234567890",
"name": "Urgent Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
10. ラベルの削除 ( delete_label )
Gmail ラベルを削除します。
{
"id": "Label_1234567890"
}
11. ラベルを取得または作成する ( get_or_create_label )
名前で既存のラベルを取得するか、存在しない場合は作成します。
{
"name": "Project XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
12. メールの一括変更（ batch_modify_emails ）
複数の電子メールのラベルを効率的に一括変更します。
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
13. メールの一括削除（ batch_delete_emails ）
複数の電子メールを効率的に一括して永久に削除します。
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
高度な検索構文
search_emailsツールは、Gmail の強力な検索演算子をサポートしています。
| オペレーター | 例 | 説明 |
|---|
from: | from:john@example.com | 特定の送信者からのメール |
to: | to:mary@example.com | 特定の受信者に送信されたメール |
subject: | subject:"meeting notes" | 件名に特定のテキストが含まれるメール |
has:attachment | has:attachment | 添付ファイル付きメール |
after: | after:2024/01/01 | デート後に受信したメール |
before: | before:2024/02/01 | デート前に受信したメール |
is: | is:unread | 特定の状態に関するメール |
label: | label:work | 特定のラベルが付いたメール |
複数の演算子を組み合わせることができます: from:john@example.com after:2024/01/01 has:attachment
高度な機能
メールコンテンツの抽出
サーバーは複雑な MIME 構造から電子メールのコンテンツをインテリジェントに抽出します。
- 利用可能な場合はプレーンテキストコンテンツを優先します
- プレーンテキストが利用できない場合は HTML コンテンツにフォールバックします
- ネストされた部分を持つマルチパートMIMEメッセージを処理します
- 添付ファイルの情報（ファイル名、種類、サイズ）を処理します
- 元のメールのヘッダー（送信元、宛先、件名、日付）を保持します
国際文字サポート
サーバーは、電子メールの件名と本文で、次のような非 ASCII 文字を完全にサポートします。
- トルコ語、中国語、日本語、韓国語、その他の非ラテン文字
- 特殊文字と記号
- 適切なエンコードにより、メールクライアントで正しく表示されます
包括的なラベル管理
サーバーは、Gmail ラベルを管理するための完全なツールセットを提供します。
- ラベルの作成: カスタマイズ可能な表示設定で新しいラベルを作成します
- ラベルを更新: ラベルの名前を変更したり、表示設定を変更したりします
- ラベルの削除: ユーザーが作成したラベルを削除します (システム ラベルは保護されています)
- 検索または作成: 名前でラベルを取得するか、見つからない場合は自動的に作成します
- すべてのラベルを一覧表示: すべてのシステム ラベルとユーザー ラベルを詳細情報とともに表示します。
- ラベルの表示オプション: メッセージとラベルリストでのラベルの表示方法を制御します
ラベルの表示設定には次のものが含まれます。
messageListVisibility : ラベルがメッセージリストに表示されるかどうかを制御します ( showまたはhide )labelListVisibility : ラベル リスト内でのラベルの表示方法を制御します ( labelShow 、 labelShowIfUnread 、またはlabelHide )
これらのラベル管理機能により、Gmail インターフェースに切り替えることなく、Claude から直接メールを高度に整理できます。
バッチ操作
サーバーには効率的なバッチ処理機能が含まれています。
- 一度に最大 50 件のメールを処理 (バッチ サイズは設定可能)
- API 制限を回避するために大量の��ール セットを自動的にチャンク化します
- 各操作の詳細な成功/失敗レポート
- 個別の再試行による適切なエラー処理
- 大量の受信トレイ管理や整理タスクに最適
セキュリティノート
- OAuth 認証情報はローカル環境 (
~/.gmail-mcp/ ) に安全に保存されます。 - サーバーは永続的な認証を維持するためにオフラインアクセスを使用します
- 資格情報をバージョン管理に共有したりコミットしたりしないでください
- Google アカウント設定で定期的に使用していないアクセスを確認し、取り消してください
- 認証情報はグローバルに保存されますが、現在のユーザーのみがアクセスできます。
トラブルシューティング
- OAuthキーが見つかりません
gcp-oauth.keys.jsonが現在のディレクトリまたは~/.gmail-mcp/にあることを確認してください。- ファイルの権限を確認する
- 資格情報の形式が無効です
- OAuthキーファイルに
webまたはinstalled認証情報が含まれていることを確認します - Webアプリケーションの場合、リダイレクトURIが正しく設定されていることを確認します。
- ポートはすでに使用されています
- ポート3000がすでに使用されている場合は、認証を実行する前にポートを解放してください。
- そのポートを使用しているプロセスを見つけて停止することができます
- バッチ操作の失敗
- バッチ操作が失敗した場合、個々の項目が自動的に再試行されます。
- 具体的な障害については詳細なエラーメッセージを確認してください
- レート制限に遭遇した場合はバッチサイズを減らすことを検討してください
貢献
貢献を歓迎します！お気軽にプルリクエストを送信してください。
評価の実行
evalsパッケージはmcpクライアントをロードし、index.tsファイルを実行するため、テスト間で再構築する必要はありません。npxコマンドの先頭に環境変数をロードすることもできます。完全なドキュメントはこちらでご覧いただけます。
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
ライセンス
マサチューセッツ工科大学
サポート
問題が発生した場合や質問がある場合は、GitHub リポジトリに問題を報告してください。