Ajbr0wn Gmail MCP Server

🚀 Gmail MCP 服務器

Gmail MCP 服務器是一個提供 Gmail 集成能力的 MCP（模型上下文協議）服務器，可供像 Claude Desktop 這樣的 MCP 客戶端使用，能讓用戶便捷地在客戶端中訪問 Gmail 相關功能。

🚀 快速開始

要使用 Gmail MCP 服務器，您需要按照以下步驟進行設置：

1. Google Cloud 項目設置：
   • 在 Google Cloud 控制檯 創建一個 Google Cloud 項目。
   • 啟用 Gmail API。
   • 創建 OAuth 2.0 憑證，應用類型選擇桌面應用，並將憑證下載為 credentials.json。
2. 安裝：

# 創建一個conda 環境
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# 安裝包
cd gmail-mcp-server
pip install -e .

3. 配置用於 Claude Desktop： 在您的 claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

請將 /path/to/ 替換為您實際的路徑。首次認證時會自動創建令牌文件。 4. 第一次運行： 當您第一次嘗試通過 Claude 訪問 Gmail 時，您會在瀏覽器中被提示授權應用程序。授權後，您的憑證將保存到令牌文件中以供以後使用。

✨ 主要特性

• 查看最新郵件：可查看您的 Gmail 收件箱中的 10 封最新郵件。
• 郵件搜索功能：支持使用 Gmail 的搜索語法搜索郵件。
• 安全身份驗證：基於 OAuth2 進行安全身份驗證，與 Gmail API 集成。

📦 安裝指南

Google Cloud 項目設置

1. 在 Google Cloud 控制檯 創建一個 Google Cloud 項目。
2. 啟用 Gmail API。
3. 創建 OAuth 2.0 憑證，應用類型選擇桌面應用，並將憑證下載為 credentials.json。

安裝依賴

# 創建一個conda 環境
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# 安裝包
cd gmail-mcp-server
pip install -e .

配置 Claude Desktop

在 claude_desktop_config.json 中添加配置：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

將 /path/to/ 替換為實際路徑，首次認證時會自動創建令牌文件。

💻 使用示例

可用資源

• gmail://inbox/recent - 返回您的 10 封最新郵件

可用工具

• search_emails
  • 描述：搜索 Gmail 郵件
  • 參數：
    • query（必需）：Gmail 搜索查詢（使用 Gmail 的標準搜索語法）
    • max_results（可選）：要返回的結果的最大數量（默認值：10）

示例搜索：

能否展示過去兩天中任何來自 sanrio 的郵件？

📚 詳細文檔

安全

此服務器需要 OAuth2 身份驗證與 Gmail：

• 首次使用時會在瀏覽器中提示您授權訪問。
• 憑證會本地保存到指定的令牌文件中。
• 可以隨時通過您的 Google 帳戶設置 revoke 授權。
• 僅請求對 Gmail 的讀取訪問權限（無寫入權限）。

環境變量

• GMAIL_CREDENTIALS_FILE（必需）：Google OAuth 憑證文件的路徑
• GMAIL_TOKEN_FILE（必需）：令牌保存的位置

為了測試，可以直接運行服務器：

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

開發

該服務器使用 Model Context Protocol 提供：

• 對最近郵件的資源訪問
• 郵件搜索工具支持
• 安全的身份驗證流程
• 自動令牌刷新

日誌記錄

服務器將詳細的操作信息記錄到 stderr，包括：

• 服務器啟動信息
• 身份驗證狀態
• 資源和工具使用情況
• 任何錯誤或問題

🔧 技術細節

該服務器基於 Model Context Protocol 構建，通過 OAuth2 與 Gmail API 進行安全集成。在首次運行時，會引導用戶進行授權，並將憑證保存到本地令牌文件中。服務器提供了對最近郵件的資源訪問和郵件搜索工具，支持使用 Gmail 的標準搜索語法。同時，服務器會自動刷新令牌，確保身份驗證的有效性。在運行過程中，會將詳細的操作信息記錄到 stderr，方便開發人員進行調試和監控。

📄 許可證

文檔中未提及許可證相關信息。

貢獻

歡迎提交拉取請求！請確保：

• 更新新功能的文檔
• 添加適當的錯誤處理
• 測試新的 OAuth 流程
• 遵循現有的代碼風格