gmail-mcp-server

gmail-mcp-server

官方代码库：https://github.com/ivanlhz/gmail-mcp-server

通过 Model Context Protocol（MCP）提供 Gmail API 的服务，专为与大模型集成以及在 Claude Desktop 等环境中使用而设计。

描述

本项目通过 MCP 提供 Gmail API，便于与大模型集成以及在 Claude Desktop 等环境中使用。

可用的 MCP 工具

该服务提供以下 MCP 工具，用于与 Gmail 交互：

工具	描述
get_labels()	获取 Gmail 用户的所有标签。
get_label_by_id(label_id)	根据 ID 获取特定标签的数据。
create_label(name, bg_color, text_color)	在 Gmail 中创建一个新标签，可选设置名称和颜色。
update_label(label_id, name, bg_color, text_color)	更新现有标签。
delete_label(label_id)	根据 ID 删除 Gmail 标签。
mark_emails_as_read(emails_ids: List[str])	将列表中指定 ID 的邮件标记为已读。
mark_emails_as_unread(emails_ids: List[str])	将列表中指定 ID 的邮件标记为未读。
add_labels(emails_ids: List[str], labels: List[str])	为 ID 列表中的所有邮件分配一个或多个标签。
get_all_emails_ids_by_query(query: str, max_results: int, next_page_token: str = None)	根据 Gmail 查询返回分页的邮件 ID 列表。使用 next_page_token 进行分页。
get_email_detail(email_id: str)	根据 ID 返回特定邮件的完整详情。

项目结构

.
├── src/
│   ├── gmail/                   # Lógica de integración con Gmail
│   │   ├── __init__.py
│   │   ├── auth.py              # Autenticación y OAuth
│   │   ├── service.py           # Lógica de negocio (mensajes, etiquetas)
│   │   └── models/
│   │       └── label_model.py   # Modelos de etiquetas de Gmail
│   ├── gmail_mcp_server/
│   │   ├── __init__.py
│   │   └── main.py              # Punto de entrada MCP y definición de tools
│   └── gmail_mcp_server.egg-info/ # Info de empaquetado
├── pyproject.toml               # Configuración del paquete y dependencias
├── uv.lock                      # Lockfile de dependencias (usado por uv)
├── README.md                    # Este archivo
├── LICENSE                      # Licencia MIT
└── .venv/                       # Entorno virtual (no versionar)

要求

• Python 3.11 或更高版本
• uv（用于管理依赖项和环境）
• build（仅在需要打包模块时）
• Claude Desktop（如果要在其中使用）

安装依赖项

1. 克隆代码库：

   git clone <URL_DEL_REPOSITORIO>
   cd gmail-mcp-server
   

2. 使用 uv 安装项目依赖项：

   uv pip install -r uv.lock
   

构建和打包

1. （可选）安装 build 工具：

   uv pip install build
   

2. 打包模块：

   uv run -m build
   

   这将在 dist/ 目录中生成 .whl 和 .tar.gz 文件。

本地安装软件包

在你的环境中安装软件包：

uv pip install dist/gmail_mcp_server-0.1.1-py3-none-any.whl

（如果版本变更，请务必调整 .whl 文件名。）

使用 uv 管理依赖项

本项目使用 uv 管理依赖项和虚拟环境。

• 安装项目的所有依赖项：

  uv pip install -r uv.lock
  

• 安装新依赖项：

  uv pip install <paquete>
  uv pip freeze > uv.lock
  

更多详情请参阅 uv 官方文档。

获取 Google 凭据（GOOGLE_CLIENT_ID 和 SECRET）

要让服务器能够访问 Gmail API，你需要在 Google Cloud 中创建 OAuth 2.0 凭据：

1. 前往 Google Cloud Console。
2. 创建新项目或选择现有项目。
3. 前往“API 和服务”>“库”，然后搜索“Gmail API”。点击“启用”。
4. 前往“API 和服务”>“凭据”，然后点击“创建凭据”>“OAuth 客户端 ID”。
5. 将应用类型选为“桌面应用”。
6. 为其命名，然后点击“创建”。
7. 下载 JSON 文件并打开，然后复制 client_id 和 client_secret 的值。
8. 启动服务器时，将这些值用作环境变量 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET。

更多信息请参阅 Google 官方指南。

与 Claude Desktop 和其他 MCP 客户端集成

Windows

• 可执行文件位于：

  C:\Users\<usuario>\develop\proyectos\mcp\gmail-mcp-server\.venv\Scripts\gmail-mcp-server.exe
  

• 你可以直接从该路径运行，也可以将 .venv\Scripts\ 添加到 PATH，以便在任何终端中使用 gmail-mcp-server。
• 如果已将 scripts 文件夹添加到 PATH（推荐）： 现在，你可以在任何终端中直接使用 gmail-mcp-server 作为全局命令。
• Claude Desktop 配置建议： 在配置文件中（例如 claude.config.json）：
  • 如果未配置 PATH：

    {
      "mcpServers": {
        "gmail": {
          "command": "C:\\Users\\<usuario>\\develop\\proyectos\\mcp\\gmail-mcp-server\\.venv\\Scripts\\gmail-mcp-server.exe",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

  • 如果已配置 PATH：

    {
      "mcpServers": {
        "gmail": {
          "command": "gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

• 将 <usuario> 替换为你的 Windows 用户名，并填写你的凭据。

Mac/Linux

• 可执行文件位于：

  /ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server
  

• 你可以直接从该路径运行。

将可执行文件永久添加到 PATH：

1. 打开 shell 配置文件（~/.bashrc、~/.zshrc 等）。
2. 添加以下行：

   export PATH="/ruta/a/tu/proyecto/.venv/bin:$PATH"
   

3. 保存文件，然后运行 source ~/.bashrc 或 source ~/.zshrc（取决于你的 shell），或者重启终端。

现在，你可以直接使用 gmail-mcp-server 作为全局命令。

• Claude Desktop 配置建议：

  • 如果未配置 PATH：

    {
      "mcpServers": {
        "gmail": {
          "command": "/ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

  • 如果已配置 PATH：

    {
      "mcpServers": {
        "gmail": {
          "command": "gmail-mcp-server",
          "env": {
            "GOOGLE_CLIENT_ID": "TU_ID",
            "GOOGLE_CLIENT_SECRET": "TU_SECRET"
          }
        }
      }
    }
    

• 将 /ruta/a/tu/proyecto/ 替换为实际路径，并填写你的凭据。

• 每次更改后，请重启 Claude Desktop，以便它正确检测并运行 MCP 服务。

参考资料

• Python 官方打包指南
• pyproject.toml 文档
• Google API Python 客户端（Gmail）
• google-auth
• dotenv（python-dotenv）
• mcp[cli]（Model Context Protocol CLI）
• Model Context Protocol（MCP）

社区与贡献

• 有疑问、建议或发现 bug？请提交 issue。
• 想要贡献？请 fork 项目并提交 pull request。欢迎贡献！
• 如有任何疑问，也可以在仓库的 Discussions 标签页中发起讨论。