Enhanced Gmail MCP Server

拡張 Gmail MCP サーバー

Python で記述された、Gmail 統合のための強力で機能豊富な Model Context Protocol（MCP）サーバーです。このサーバーを使うと、Claude などの AI アシスタントが自然言語を通じて Gmail を操作でき、包括的なメール管理機能を利用できます。

🌟 主な機能

📧 メール管理全般

• 件名、本文、宛先をカスタマイズしてメールを送信
• すべてのメタデータとともにメールの内容を読み取り、取得
• 確認を行ってメールをゴミ箱に移動
• メールを既読または未読に設定
• ブラウザーでメールを直接開く

📝 下書きの管理

• 後で確認するためのメールの下書きを作成
• すべての下書きメールを一覧表示
• 既存の下書きを編集

🏷️ 高度なラベル管理

• 利用可能なすべてのラベルを一覧表示
• カスタムラベルを作成
• メールにラベルを適用／削除
• 既存のラベル名を変更
• 使用していないラベルを削除
• ラベルでメールを検索

📁 フォルダーの整理

• 新しいフォルダーを作成（Gmail のラベルとして実装）
• フォルダー間でメールを移動
• 利用可能なすべてのフォルダーを一覧表示

🔍 強力な検索と絞り込み

• Gmail の高度な検索クエリ構文を使ってメールを検索
• メールフィルターを作成、管理、削除
• 送信者、宛先、件名、本文などで絞り込み
• 柔軟なパラメーターで検索結果をカスタマイズ

🗄️ アーカイブの管理

• メールをアーカイブ（削除せずに受信トレイから移動）
• 検索条件に一致する複数のメールを一括でアーカイブ
• アーカイブ済みメールをすべて一覧表示
• アーカイブ済みメールを受信トレイに復元

🚀 はじめに

前提条件

• Python 3.12+
• Python MCP SDK >= 2.0
• Gmail API が有効になっている Google Cloud プロジェクト
• OAuth 2.0 認証情報

インストール

# Clone the repository
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Google Cloud の設定

1. 新しい Google Cloud プロジェクトを作成します
2. Gmail APIを有効にします
3. OAuth 同意画面を設定します：
   • ユーザーの種類として「External」を選択します
   • メールアドレスをテストユーザーとして追加します
   • スコープを追加します：https://www.googleapis.com/auth/gmail/modify
4. OAuth 2.0 認証情報を作成します：
   • アプリケーションの種類として「Desktop app」を選択します
   • JSON 認証情報ファイルをダウンロードします

設定

認証情報を安全に保管し、サーバーの実行時にその場所を指定します：

# Example directory structure for credentials
mkdir -p ~/.gmail-mcp
# Move your downloaded credentials file
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 使い方

Claude Desktop で実行する

Claude Desktop の設定ファイル（通常は ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加します：

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

MCP Inspector でテストする

テストとデバッグには、MCP Inspector を使用します：

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 セキュリティに関する考慮事項

• 認証情報やトークンファイルをバージョン管理に登録しないでください
• 適切なアクセス権を設定した安全な場所に認証情報を保管します
• サーバーは、機密性の高い操作を実行する前にユーザーの確認を求めます
• Google Cloud Console を定期的に確認し、不審なアクティビティがないか確認します
• 機密性の高いパスには環境変数の使用を検討してください

🛠️ アーキテクチャ

この実装は、Google API クライアントライブラリを通じてすべての Gmail 操作を処理する、包括的な単一ファイルアーキテクチャを採用しています。主なコンポーネントは次のとおりです：

• トークンを自動更新する OAuth2 認証
• 包括的なエラー処理とログ記録
• 明確な入力スキーマを備えた構造化ツール定義
• 効率的なメールの解析と書式設定

📚 プロンプトの例

Gmail MCP サーバーに接続した後、Claude で次のプロンプトを試してください：

• 「未読メールを表示して」
• 「添付ファイルのある、[email protected] からのメールを検索して」
• 「『Important Projects』という新しいラベルを作成して」
• 「近日中の会議について、[email protected] 宛てのメールの下書きを作成して」
• 「[email protected] からのメールをすべてアーカイブして」
• 「チームからのメールに自動でラベルを付けるフィルターを作成して」

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトはGPL-3.0ライセンスの下でライセンスされています。詳細はLICENSEファイルをご覧ください。

🙏 謝辞

• コミュニティのさまざまなMCP サーバー実装に着想を得ています
• Model Context Protocolフレームワークを使用して構築されています
• Googleの公式APIクライアントライブラリを使用しています