Gmail MCP Server

Gmail MCP Server は、Node.js/TypeScript ベースの MCP stdio サーバーであり、OpenClaw が Model Context Protocol を通じて Gmail のメールを読み取れるようにします。

機能

Gmail API OAuth 2.0 認証を使用。権限範囲は読み取り専用：https://www.googleapis.com/auth/gmail.readonly
list_emails：受信トレイのメールを一覧表示。maxResults および Gmail の query フィルタをサポート
get_email：messageId を通じて個別のメール詳細を読み取り
search_emails：Gmail の検索構文を使用してメールを検索
list_labels：すべての Gmail ラベル/フォルダを一覧表示
MCP stdio トランスポートをサポートし、OpenClaw からの呼び出しが可能

環境要件

Node.js 18 以上
npm
Gmail API にアクセス可能な Google アカウント

インストール

npm install
npm run build

Google Cloud Console での OAuth 認証情報の作成

Google Cloud Console を開きます。
プロジェクトを作成または選択します。
APIs & Services -> Library に移動し、Gmail API を検索して有効にします。
APIs & Services -> OAuth consent screen に移動します。
ユーザータイプを選択します。個人利用の場合は通常 External を選択します。
アプリ名、ユーザーサポートメール、デベロッパー連絡先メールアドレスを入力します。
Scopes ステップで Gmail の読み取り専用権限を追加します：https://www.googleapis.com/auth/gmail.readonly。
アプリがテスト状態の場合は、Test users に自分の Gmail アカウントを追加します。
APIs & Services -> Credentials に移動します。
Create Credentials -> OAuth client ID をクリックします。
Application type で Desktop app を選択します。
作成後に JSON ファイルをダウンロードします。

credentials.json の配置

設定ディレクトリを作成し、ダウンロードした OAuth JSON を以下のように保存します：

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

最終的なパスは以下の通りである必要があります：

~/.gmail-mcp/credentials.json

認証フローの実行

npm run auth

スクリプトは以下の処理を行います：

一時的なローカル OAuth コールバックサーバーを起動
ブラウザを開いて Google 認証を実行
認証完了後、トークンを ~/.gmail-mcp/token.json に保存

ブラウザが自動的に開かない場合は、ターミナルに表示された認証 URL を手動でブラウザにコピーしてください。

MCP Server の起動

npm run start

start は stdio トランスポートを使用します。通常は OpenClaw が MCP サーバーのサブプロセスとして起動するため、手動で常時実行する必要はありません。

OpenClaw MCP 設定例

コマンドを本プロジェクトのビルド後のエントリポイントに向けます：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

プロジェクトディレクトリ内で npm を使用して起動することも可能です：

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Tools パラメータの説明

list_emails

受信トレイのメールを一覧表示します。

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}

maxResults：オプション、デフォルト 10、最大 50
query：オプション、Gmail 検索構文、INBOX 内の検索に限定されます

get_email

個別のメール詳細を読み取ります。

{
  "messageId": "18f..."
}

返されるフィールドには、送信者、受信者、件名、日付、ラベル、本文テキスト、HTML 本文、および添付ファイルのメタデータが含まれます。

search_emails

Gmail のメールを検索します。

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}

query：必須、Gmail 検索構文をサポート
maxResults：オプション、デフォルト 10、最大 50

list_labels

すべてのラベル/フォルダを一覧表示します。

{}

ファイルの場所

OAuth credentials：~/.gmail-mcp/credentials.json
OAuth token：~/.gmail-mcp/token.json
MCP server エントリポイント：dist/src/index.js

よくある質問

Missing Gmail OAuth credentials

Google OAuth クライアント JSON がダウンロード済みであり、以下に保存されていることを確認してください：

~/.gmail-mcp/credentials.json

Missing Gmail OAuth token

先に以下を実行してください：

npm run auth

access_denied またはアプリが未検証

OAuth consent screen がまだテスト状態の場合は、現在の Gmail アカウントを Test users に追加する必要があります。

invalid_grant

古いトークンを削除してから再認証してください：

rm ~/.gmail-mcp/token.json
npm run auth

gmail-mcp