MCP Headless Gmail Server

MCP Headless Gmail サーバー（NPM と Docker）

ローカルでの認証情報やトークンの設定なしで、Gmail の取得と送信を可能にする MCP（Model Context Protocol）サーバーです。

MCP Headless Gmail サーバーを選ぶ理由

主な利点

• ヘッドレスかつリモートでの動作：Docker の外部での実行やローカルファイルへのアクセスが必要な他の MCP Gmail ソリューションとは異なり、このサーバーはブラウザーもローカルファイルへのアクセスも不要で、リモート環境で完全にヘッドレスで動作します。
• 分離されたアーキテクチャ：任意のクライアントで OAuth フローを個別に完了し、その後、認証情報をコンテキストとしてこの MCP サーバーに渡せます。これにより、認証情報の保存とサーバーの実装を完全に分離できます。

あると便利な特徴

• 機能を絞った設計：特にマーケティング用途など、多くのユースケースでは Gmail へのアクセスだけが必要で、カレンダーなどの追加の Google サービスは必要ありません。そのような用途に最適な、機能を絞った実装です。
• Docker 対応：適切に分離され、環境に依存しない、ワンクリックでのセットアップを実現するため、コンテナー化を念頭に設計されています。
• 信頼性の高い依存関係：十分に保守されている google-api-python-client ライブラリを基盤としています。

機能

• Gmail の最新メールを、本文の先頭 1k 文字とともに取得
• offset パラメーターを使い、本文全体を 1k 文字ずつ取得
• Gmail 経由でメールを送信
• アクセストークンを個別に更新
• リフレッシュトークンを自動処理

前提条件

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

インストール

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

# Install dependencies
pip install -e .

Docker

Docker イメージのビルド

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

Claude Desktop での使用

Claude Desktop で Docker イメージを使用するには、Claude の設定に以下を追加します。

docker

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

npm 版

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

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

クロスプラットフォーム向けの公開

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

1. 新しいビルダーインスタンスを作成する（まだ作成していない場合）：

   docker buildx create --use
   

2. 複数のプラットフォーム向けにイメージをビルドしてプッシュする：

   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
   

3. 指定したプラットフォームでイメージが利用可能であることを確認する：

   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、threadId、from、to、subject、date など）
• メール本文の最初の1,000文字
• 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
}

レスポンスには以下が含まれます。

• 指定したオフセットから始まる、メール本文の1,000文字分のチャンク
• body_size_bytes：メール本文の合計サイズ
• chunk_size：返されたチャンクのサイズ
• contains_full_body：チャンクに本文の残りすべてが含まれているかを示すブール値

長いメッセージのメール本文全体を取得するには、contains_full_body が true になるまで、オフセットを毎回1,000ずつ増やして順番に呼び出します。

メールの送信

{
  "google_access_token": "your_access_token",
  "to": "[email protected]",
  "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>"
}

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

1. 次のいずれかを指定して、gmail_refresh_token ツールを呼び出します。
   • すべての認証情報（アクセストークン、リフレッシュトークン、クライアント ID、クライアントシークレット）
   • アクセストークンの期限が切れている場合は、リフレッシュトークン、クライアント ID、クライアントシークレットのみ
2. 返された新しいアクセストークンを、その後の API 呼び出しで使用します。
3. トークンの期限切れを示すレスポンスが返された場合は、gmail_refresh_token ツールを再度呼び出して新しいトークンを取得します。

この方法により、ほとんどの API 呼び出しでクライアント認証情報を毎回指定する必要がなくなり、必要に応じてトークンを更新できます。

Google API 認証情報の取得

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

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成します
3. Gmail API を有効にします
4. OAuth 同意画面を設定します
5. OAuth クライアント ID の認証情報を作成します（アプリケーションの種類として「Desktop app」を選択します）
6. クライアント ID とクライアントシークレットを保存します
7. 次のスコープを指定して OAuth 2.0 を使用し、アクセストークンとリフレッシュトークンを取得します。
   • https://www.googleapis.com/auth/gmail.readonly（メールの読み取り用）
   • https://www.googleapis.com/auth/gmail.send（メールの送信用）

トークンの更新

このサーバーはトークンの自動更新に対応しています。アクセストークンの期限が切れると、Google API クライアントはリフレッシュトークン、クライアント ID、クライアントシークレットを使用して、新しいアクセストークンを取得します。この処理にユーザーの操作は必要ありません。

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

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

ライセンス

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