MCP ヘッドレス Gmail サーバー

ローカル認証情報やトークンの設定なしで Gmail の取得、送信ができる MCP (Model Context Protocol) サーバー。

MCP ヘッドレス Gmail サーバーを選ぶ理由

重要な利点

ヘッドレス & リモート操作: Docker 外での実行とローカルファイルアクセスを必要とする他の MCP Gmail ソリューションとは異なり、このサーバーはブラウザーもローカルファイルアクセスもないリモート環境で完全にヘッドレスで実行できます。
分離されたアーキテクチャ: どのクライアントも OAuth フローを独立して完了し、資格情報をコンテキストとしてこの MCP サーバーに渡すことができるため、資格情報の保存とサーバーの実装が完全に分離されます。

いいけど批判的ではない

重点的な機能: 多くのユースケース、特にマーケティングアプリケーションでは、カレンダーなどの追加の Google サービスなしで Gmail へのアクセスのみが必要なため、この重点的な実装が理想的です。
Docker 対応: コンテナ化を考慮して設計されており、適切に分離された、環境に依存しないワンクリックセットアップを実現します。
信頼できる依存関係: 適切に管理された google-api-python-client ライブラリに基づいて構築されています。

特徴

Gmail から最新のメールを本文の最初の 1,000 文字で取得します
オフセットパラメータを使用して、1k チャンクでメール本文の全内容を取得します。
Gmail経由でメールを送信する
アクセストークンを個別に更新する
自動リフレッシュトークン処理

前提条件

Python 3.10以上
Google API 認証情報（クライアント ID、クライアントシークレット、アクセストークン、リフレッシュトークン）

インストール

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

# Install dependencies
pip install -e .

ドッカー

Dockerイメージの構築

# Build the Docker image
docker build -t mcp-headless-gmail .

Claude Desktopでの使用

Dockerの使用

Claude 構成に以下を追加することで、Claude Desktop が Docker イメージを使用するように構成できます。

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

注: この設定では、「ツールの使用」セクションに示されているように、ツール呼び出し時にGoogle API認証情報を提供する必要があります。認証情報の保存とサーバー実装を分離するため、Gmailの認証情報は環境変数として渡されません。

クロスプラットフォームパブリッシング

複数のプラットフォーム向けにDockerイメージを公開するには、 docker buildxコマンドを使用します。以下の手順に従ってください。

新しいビルダーインスタンスを作成します(まだ作成していない場合)。
docker buildx create --use
複数のプラットフォーム用のイメージをビルドしてプッシュします。
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
指定されたプラットフォームでイメージが使用可能であることを確認します。
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

使用法

サーバーはMCPツールを通じてGmail機能を提供します。専用のトークン更新ツールにより、認証処理が簡素化されます。

サーバーの起動

mcp-server-headless-gmail

ツールの使用

Claude のような MCP クライアントを使用する場合、認証を処理する主な方法は 2 つあります。

トークンの更新（最初のステップまたはトークンの有効期限が切れたとき）

アクセストークンとリフレッシュトークンの両方がある場合:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

アクセストークンの有効期限が切れている場合は、リフレッシュトークンだけで更新できます。

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

これにより、新しいアクセストークンとその有効期限が返され、後続の呼び出しで使用できるようになります。

最近のメールを取得する

各メール本文の最初の 1,000 文字を含む最近のメールを取得します。

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

回答には以下が含まれます:

電子メールのメタデータ (ID、スレッド ID、送信元、送信先、件名、日付など)
メール本文の最初の1000文字
body_size_bytes : メール本文の合計サイズ（バイト単位）
contains_full_body : 本文全体が含まれているか（true）、切り捨てられているか（false）を示すブール値

メール本文の全文を取得する

本文が 1,000 文字を超えるメールの場合は、完全なコンテンツをチャンク単位で取得できます。

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

スレッド ID でメールの内容を取得することもできます。

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

応答には次のものが含まれます。

指定されたオフセットから始まるメール本文の1kチャンク
body_size_bytes : メール本文の合計サイズ
chunk_size : 返されるチャンクのサイズ
contains_full_body : チャンクに本体の残りが含まれているかどうかを示すブール値

長いメッセージのメール本文全体を取得するには、 contains_full_body true になるまで、オフセットを 1000 ずつ増やしながら連続呼び出しを実行します。

メールを送信する

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

トークン更新ワークフロー

まず、次のいずれかの方法でgmail_refresh_tokenツールを呼び出します。
- 完全な認証情報（アクセストークン、リフレッシュトークン、クライアントID、クライアントシークレット）、または
- アクセストークンの有効期限が切れている場合は、リフレッシュトークン、クライアントID、クライアントシークレットのみ
返された新しいアクセストークンを後続の API 呼び出しに使用します。
トークンの有効期限が切れたことを示す応答を受け取った場合は、 gmail_refresh_tokenツールを再度呼び出して新しいトークンを取得してください。

このアプローチでは、すべての操作でクライアント資格情報を要求せず、必要なときにトークンの更新も可能にすることで、ほとんどの API 呼び出しが簡素化されます。

Google API認証情報の取得

必要な Google API 認証情報を取得するには、次の手順に従います。

Google Cloud Consoleにアクセスします
新しいプロジェクトを作成する
Gmail APIを有効にする
OAuth同意画面を設定する
OAuth クライアント ID 資格情報を作成します (アプリケーションの種類として「デスクトップアプリ」を選択します)
クライアントIDとクライアントシークレットを保存する
OAuth 2.0 を使用して、次のスコープのアクセストークンと更新トークンを取得します。
- https://www.googleapis.com/auth/gmail.readonly (メールを読むため)
- https://www.googleapis.com/auth/gmail.send (メール送信用)

トークンの更新

このサーバーはトークンの自動更新を実装しています。アクセストークンの有効期限が切れると、Google APIクライアントはリフレッシュトークン、クライアントID、クライアントシークレットを使用して、ユーザーの介入なしに新しいアクセストークンを取得します。

セキュリティに関する注意事項

このサーバーはGoogle API認証情報に直接アクセスする必要があります。トークンと認証情報は常に安全に保管し、信頼できない相手と共有しないでください。

ライセンス

詳細については、LICENSE ファイルを参照してください。

MCP Headless Gmail Server

Integrations

MCP ヘッドレス Gmail サーバー