Gmail MCPサーバー

Gmailへの読み取り専用アクセスを提供するModel Context Protocol (MCP) サーバーです。Claude Codeが安全にGmailの受信トレイを検索、読み取り、分析できるようにします。

機能

• search_emails - Gmailのクエリ構文を使用して検索

• list_unread - 未読メールを一覧表示

• get_message - 添付ファイルメタデータを含むメッセージの全内容を取得

• get_thread - 会話スレッド内の全メッセージを取得

• draft_reply - 返信ドラフトの内容を準備（送信は行いません）

Related MCP server: Gmail MCP Server

前提条件

• Node.js 18以上

• Gmail APIが有効なGoogle Cloudプロジェクト

• OAuth 2.0 デスクトップアプリの認証情報

Google Cloudの設定

1. Google Cloudプロジェクトの作成

1. Google Cloud Console にアクセスします

2. 「プロジェクトを選択」→「新しいプロジェクト」をクリックします

3. プロジェクト名を入力します（例: "Gmail MCP Server"）

4. 「作成」をクリックします

2. Gmail APIの有効化

1. プロジェクト内で「APIとサービス」→「ライブラリ」に移動します

2. 「Gmail API」を検索します

3. クリックして「有効にする」を押します

3. OAuth同意画面の設定

1. 「APIとサービス」→「OAuth同意画面」に移動します

2. 「外部」（Google Workspaceを使用している場合は「内部」）を選択します

3. 必須フィールドを入力します:

   • アプリ名: "Gmail MCP Server"

   • ユーザーサポートメール: あなたのメールアドレス

   • デベロッパーの連絡先情報: あなたのメールアドレス

4. 「保存して次へ」をクリックします

5. スコープを追加します:

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. テストユーザーとして自分のメールアドレスを追加します（外部の場合）

7. 設定を完了します

4. OAuth認証情報の作成

1. 「APIとサービス」→「認証情報」に移動します

2. 「認証情報を作成」→「OAuthクライアントID」をクリックします

3. アプリケーションの種類として「デスクトップアプリ」を選択します

4. 名前を付けます（例: "Gmail MCP Desktop"）

5. 「作成」をクリックします

6. クライアントIDとクライアントシークレットをダウンロードまたはコピーします

インストール

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

設定

1. サンプル環境ファイルをコピーします:

cp .env.example .env

2. OAuth認証情報を使用して .env を編集します:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

初回実行（認証）

サーバーを初めて実行すると、以下の処理が行われます:

1. Google認証のためにブラウザが開きます

2. サインインと権限の付与を求められます

3. トークンがローカルの token.json に保存されます

以降の実行では、保存されたトークンが自動的に再利用されます。

Claude Codeでの使用

MCPサーバーの追加

claude mcp add gmail node ./dist/index.js

または、Claude Codeの設定に手動で追加します:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

利用可能なツール

search_emails

Gmailのクエリ構文を使用してメールを検索します。

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

未読メールを一覧表示します（is:unread 検索のショートカット）。

get_message

メッセージIDを指定して、特定のメールの全内容を取得します。

get_thread

スレッドIDを指定して、会話スレッド内の全メッセージを取得します。

draft_reply

スレッドへの返信ドラフトを準備します。返信を作成するためのコンテキストを提供しますが、メールの送信は行いません。

開発

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

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

• OAuthトークンはローカルの token.json に保存されます

• .env や token.json をバージョン管理にコミットしないでください

• サーバーは読み取りと作成の権限のみを要求します

• メールは送信されません - draft_reply は内容を準備するだけです

• メールの内容はログに記録されません

トラブルシューティング

"Missing CLIENT_ID or CLIENT_SECRET"

.env ファイルが存在し、有効な認証情報が含まれていることを確認してください。

"Authorization timeout"

OAuthフローには5分間のタイムアウトがあります。サーバーを再起動し、速やかに認証を完了してください。

"Token refresh failed"

token.json を削除して、再度認証を行ってください。

"Access blocked: This app's request is invalid"

OAuth同意画面が適切に設定されていること、およびテストユーザーとしてメールアドレスが追加されていることを確認してください。