gmail-mcp-server

gmail-mcp-server

公式リポジトリ：https://github.com/ivanlhz/gmail-mcp-server

Gmail APIをModel Context Protocol（MCP）経由で公開するサーバーです。LLMとの統合や、Claude Desktopなどの環境での利用を想定して設計されています。

説明

このプロジェクトでは、Gmail APIをMCP経由で公開し、LLMとの統合やClaude Desktopなどの環境での利用を容易にします。

利用可能なMCPツール

このサーバーは、Gmailとやり取りするための次のMCPツールを公開します。

ツール	説明
get_labels()	Gmailユーザーのすべてのラベルを取得します。
get_label_by_id(label_id)	IDを指定して、特定のラベルのデータを取得します。
create_label(name, bg_color, text_color)	名前と任意の色を指定して、Gmailに新しいラベルを作成します。
update_label(label_id, name, bg_color, text_color)	既存のラベルを更新します。
delete_label(label_id)	IDを指定して、Gmailのラベルを削除します。
mark_emails_as_read(emails_ids: List[str])	リストで指定されたIDのメールを既読にします。
mark_emails_as_unread(emails_ids: List[str])	リストで指定されたIDのメールを未読にします。
add_labels(emails_ids: List[str], labels: List[str])	IDのリストで指定されたすべてのメールに、1つ以上のラベルを割り当てます。
get_all_emails_ids_by_query(query: str, max_results: int, next_page_token: str = None)	Gmailの検索クエリに基づき、ページ分割されたメールIDのリストを返します。ページ分割には next_page_token を使用します。
get_email_detail(email_id: str)	IDを指定して、特定のメールの詳細情報をすべて返します。

プロジェクトの構成

.
├── src/
│   ├── gmail/                   # Lógica de integración con Gmail
│   │   ├── __init__.py
│   │   ├── auth.py              # Autenticación y OAuth
│   │   ├── service.py           # Lógica de negocio (mensajes, etiquetas)
│   │   └── models/
│   │       └── label_model.py   # Modelos de etiquetas de Gmail
│   ├── gmail_mcp_server/
│   │   ├── __init__.py
│   │   └── main.py              # Punto de entrada MCP y definición de tools
│   └── gmail_mcp_server.egg-info/ # Info de empaquetado
├── pyproject.toml               # Configuración del paquete y dependencias
├── uv.lock                      # Lockfile de dependencias (usado por uv)
├── README.md                    # Este archivo
├── LICENSE                      # Licencia MIT
└── .venv/                       # Entorno virtual (no versionar)

要件

• Python 3.11以降
• uv（依存関係と環境の管理用）
• build（モジュールをパッケージ化する場合のみ）
• Claude Desktop（そこで使用する場合）

依存関係のインストール

1. リポジトリをクローンします。

   git clone <URL_DEL_REPOSITORIO>
   cd gmail-mcp-server
   

2. uvを使ってプロジェクトの依存関係をインストールします。

   uv pip install -r uv.lock
   

ビルドとパッケージ化

1. （任意）buildツールをインストールします。

   uv pip install build
   

2. モジュールをパッケージ化します。

   uv run -m build
   

   これにより、dist/ ディレクトリに .whl ファイルと .tar.gz ファイルが生成されます。

パッケージのローカルインストール

パッケージを環境にインストールします。

uv pip install dist/gmail_mcp_server-0.1.1-py3-none-any.whl

（バージョンが変わった場合は、.whl ファイルの名前を調整してください。）

uv による依存関係の管理

このプロジェクトでは、依存関係と仮想環境の管理に uv を使用します。

• プロジェクトのすべての依存関係をインストールします：

  uv pip install -r uv.lock
  

• 新しい依存関係をインストールします：

  uv pip install <paquete>
  uv pip freeze > uv.lock
  

詳しくは、uv の公式ドキュメントをご覧ください。

Google の認証情報（GOOGLE_CLIENT_ID と SECRET）の取得

サーバーから Gmail API にアクセスするには、Google Cloud で OAuth 2.0 認証情報を作成する必要があります：

1. Google Cloud Console にアクセスします。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. 「API とサービス」>「ライブラリ」に移動し、「Gmail API」を検索します。「有効にする」をクリックします。
4. 「API とサービス」>「認証情報」に移動し、「認証情報を作成」>「OAuth クライアント ID」をクリックします。
5. アプリケーションの種類として「デスクトップアプリ」を選択します。
6. 名前を入力して「作成」をクリックします。
7. JSON ファイルをダウンロードして開き、client_id と client_secret の値をコピーします。
8. サーバーの起動時に、これらの値を環境変数 GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET として使用します。

詳しくは、Google の公式ガイドをご覧ください。

Claude Desktop およびその他の MCP クライアントとの統合

Windows

• 実行ファイルの場所：

  C:\Users\<usuario>\develop\proyectos\mcp\gmail-mcp-server\.venv\Scripts\gmail-mcp-server.exe
  

• このパスから直接実行するか、.venv\Scripts\ を PATH に追加すると、任意のターミナルから gmail-mcp-server を使用できます。
• スクリプトフォルダーを PATH に追加した場合（推奨）： これで、任意のターミナルからグローバルコマンドとして gmail-mcp-server を実行できます。
• Claude Desktop の推奨設定： 設定ファイル（例：claude.config.json）に次のように記述します：
  • PATH を設定していない場合：

    {
      "mcpServers": {
        "gmail": {
          "command": "C:\\Users\\<usuario>\\develop\\proyectos\\mcp\\gmail-mcp-server\\.venv\\Scripts\\gmail-mcp-server.exe",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

  • PATH を設定している場合：

    {
      "mcpServers": {
        "gmail": {
          "command": "gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

• <usuario> を Windows のユーザー名に置き換え、認証情報を入力します。

Mac/Linux

• 実行ファイルの場所：

  /ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server
  

• このパスから直接実行できます。

実行ファイルを PATH に恒久的に追加する方法：

1. シェルの設定ファイル（~/.bashrc、~/.zshrc など）を開きます。
2. 次の行を追加します：

   export PATH="/ruta/a/tu/proyecto/.venv/bin:$PATH"
   

3. ファイルを保存し、source ~/.bashrc または source ~/.zshrc（使用中のシェルに応じて）を実行するか、ターミナルを再起動します。

これで、グローバルコマンドとして gmail-mcp-server を実行できます。

• Claude Desktop の推奨設定：

  • PATH を設定していない場合：

    {
      "mcpServers": {
        "gmail": {
          "command": "/ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

  • PATH を設定している場合：

    {
      "mcpServers": {
        "gmail": {
          "command": "gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

• /ruta/a/tu/proyecto/ を実際のパスに置き換え、認証情報を入力します。

• 変更を加えた後は、Claude Desktop を再起動して、MCP サーバーが正しく検出され実行されるようにします。

参考資料

• Python パッケージング公式ガイド
• pyproject.toml ドキュメント
• Google API Python Client（Gmail）
• google-auth
• dotenv（python-dotenv）
• mcp[cli]（Model Context Protocol CLI）
• Model Context Protocol（MCP）

コミュニティと貢献

• 質問や提案がある場合、またはバグを見つけた場合は、issueを作成してください。
• 貢献したい場合は、フォークしてプルリクエストを送ってください。貢献を歓迎します！
• お問い合わせは、リポジトリのDiscussionsタブでディスカッションを開始していただくこともできます。