Skip to main content
Glama
deenesjakoruzh
baryhuang

MCP Headless Gmail Server

by baryhuang
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

MCP ヘッドレス Gmail サーバー

npmバージョン Dockerプル ライセンス: MIT

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

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

重要な利点

  • ヘッドレス & リモート操作: Docker 外での実行とローカル ファイル アクセスを必要とする他の MCP Gmail ソリューションとは異なり、このサーバーはブラウザーもローカル ファイル アクセスもないリモート環境で完全にヘッドレスで実行できます。

  • 分離されたアーキテクチャ: どのクライアントも OAuth フローを独立して完了し、資格情報をコンテキストとしてこの MCP サーバーに渡すことができるため、資格情報の保存とサーバーの実装が完全に分離されます。

いいけど批判的ではない

  • 重点的な機能: 多くのユースケース、特にマーケティング アプリケーションでは、カレンダーなどの追加の Google サービスなしで Gmail へのアクセスのみが必要なため、この重点的な実装が理想的です。

  • Docker 対応: コンテナ化を考慮して設計されており、適切に分離された、環境に依存しない、ワンクリック セットアップが可能です。

  • 信頼できる依存関係: 適切に管理された google-api-python-client ライブラリに基づいて構築されています。

Related MCP server: Systemprompt MCP Gmail Server

特徴

  • Gmail から最新のメールを本文の最初の 1,000 文字で取得します

  • オフセットパラメータを使用して、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イメージの構築

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

Claude Desktopでの使用

Claude 構成に以下を追加することで、Claude Desktop が 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、スレッド 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>"
}

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

  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 資格情報を作成します (アプリケーションの種類として「デスクトップ アプリ」を選択します)

  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 ファイルを参照してください。

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/baryhuang/mcp-headless-gmail'

If you have feedback or need assistance with the MCP directory API, please join our Discord server