MCP Gmail Server

MCP Gmail サーバー

MCP Python SDK を使用して、LLM に Gmail へのアクセスを提供する Model Context Protocol（MCP）サーバーです。

機能

• Gmail のメッセージを MCP リソースとして公開します
• メールの作成、送信、管理を行うツールを提供します
• Google の Gmail API を使用した OAuth 2.0 認証に対応します

前提条件

• Python 3.10+
• API にアクセスできる Gmail アカウント
• Python パッケージ管理用の uv（推奨）

セットアップ

1. 依存関係のインストール

プロジェクトの依存関係をインストールします（uv は仮想環境を自動的に作成し、管理します）

uv sync

2. Gmail OAuth 認証情報の設定

残念ながら、Gmail API の使用には多くの手順が必要です。2025 年 3 月 28 日時点で必要な手順をすべて記載するよう努めましたが、変更される可能性があります。

Google Cloud のセットアップ

1. Google Cloud プロジェクトを作成する

   • Google Cloud Console にアクセスします
   • ページ上部のプロジェクトのドロップダウンをクリックします
   • 「New Project」をクリックします
   • プロジェクト名（例：「MCP Gmail Integration」）を入力します
   • 「Create」をクリックします
   • プロジェクトが作成されるまで待ち、ドロップダウンから選択します

2. Gmail API を有効にする

   • Google Cloud プロジェクトで、ナビゲーションメニュー（≡）を開きます
   • 「APIs & Services」>「Library」を選択します
   • 「Gmail API」を検索します
   • Gmail API のカードをクリックします
   • 「Enable」をクリックします

3. OAuth 同意画面を設定する

   • 「APIs & Services」>「OAuth consent screen」に移動します
   • 「Google Auth Platform not configured yet」のようなメッセージが表示される場合があります
     • 「Get started」をクリックします
   • 必要なアプリケーション情報を入力します：
     • アプリ名：「MCP Gmail Integration」
     • ユーザーサポートメール：ご自身のメールアドレス
   • 必要な対象ユーザー情報を入力します：
     • ユーザータイプに「External」を選択します（Google Workspace 組織をお持ちの場合を除く）
   • 必要な連絡先情報を入力します：
     • ご自身のメールアドレス
   • 「Save and Continue」をクリックします
   • 「Create」をクリックします

4. OAuth 認証情報を作成する

   • 「APIs & Services」>「Credentials」に移動します
   • 「Create Credentials」>「OAuth client ID」をクリックします
   • アプリケーションの種類として「Desktop app」を選択します
   • 名前（例：「MCP Gmail Desktop Client」）を入力します
   • 「Create」をクリックします
   • 作成した認証情報の「Download JSON」をクリックします
   • ファイルをプロジェクトのルートディレクトリに credentials.json として保存します

5. スコープを追加する

   • 「APIs & Services」>「OAuth consent screen」に移動します
   • 「Data Access」タブに移動します
   • 「Add or remove scopes」をクリックします
   • Gmail API を検索します
   • Gmail アカウントのメールの「読み取り、作成、送信」を許可する .../auth/gmail.modify のスコープを選択します
   • 「update」をクリックします
   • 「save」をクリックします

簡単なテストスクリプトを実行して、OAuth の設定が正しく完了していることを確認してください。

uv run python scripts/test_gmail_setup.py

https://console.cloud.google.com/apis/api/gmail.googleapis.com/metrics で使用状況の指標を確認できます。

3. サーバーを実行する

開発モード：

uv run mcp dev mcp_gmail/server.py

これにより、MCP サーバーと対話するための MCP Inspector アプリケーションが起動します。

または、Claude Desktop で使用するためにインストールします：

uv run mcp install \
    --with-editable .
    --name gmail \
    --env-var MCP_GMAIL_CREDENTIALS_PATH=$(pwd)/credentials.json \
    --env-var MCP_GMAIL_TOKEN_PATH=$(pwd)/token.json \
    mcp_gmail/server.py

メモ

Claude Desktop の起動時に Error: spawn uv ENOENT のようなエラーが発生し、MCP サーバーの初期化に失敗する場合は、uv の絶対パスを指定するように claude_desktop_config.json を更新する必要があります。Claude Desktop -> Settings -> Developer -> Edit Config に移動してください。

{
  "mcpServers": {
    "gmail": {
      "command": "~/.local/bin/uv",
    }
  }
}

開発

リントとテスト

リントとフォーマットを実行します：

# Format code
uv run ruff format .

# Lint code with auto-fixes where possible
uv run ruff check --fix .

# Run tests
uv run pytest tests/

Pre-commit フック

このプロジェクトでは、コード品質を確保するために pre-commit フックを使用しています。フックはコミットごとに自動実行され、コードのフォーマットとリントの基準を確認します。

pre-commit フックをインストールします：

pre-commit install

すべてのファイルに対して pre-commit を手動で実行します：

pre-commit run --all-files

使用方法

起動後は、任意の MCP クライアントまたは Claude Desktop を使用して MCP サーバーに接続できます。

利用可能なリソース

• gmail://messages/{message_id} - メールメッセージにアクセスします
• gmail://threads/{thread_id} - メールスレッドにアクセスします

利用可能なツール

• compose_email - 新しいメールの下書きを作成します
• send_email - メールを送信します
• search_emails - 特定のフィルター（送信元、宛先、件名、日付など）でメールを検索します
• query_emails - Gmail のクエリ構文を使用してメールを検索します
• get_emails - ID を指定して複数のメールメッセージを取得します
• list_available_labels - 利用可能な Gmail ラベルをすべて取得します
• mark_message_read - メッセージを既読にします
• add_label_to_message - メッセージにラベルを追加します
• remove_label_from_message - メッセージからラベルを削除します

環境変数

環境変数を使用してサーバーを設定できます。

• MCP_GMAIL_CREDENTIALS_PATH：OAuth 認証情報 JSON ファイルのパス（デフォルト："credentials.json"）
• MCP_GMAIL_TOKEN_PATH：OAuth トークンの保存先パス（デフォルト："token.json"）
• MCP_GMAIL_MAX_RESULTS：検索クエリのデフォルトの最大結果数（デフォルト：10）

ライセンス

MIT