使用说明

项目简介

FastMCP G Suite Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，它使用 'fastmcp' 框架，旨在为 LLM 客户端提供与 Google Workspace (G Suite) 产品交互的上下文信息和功能。该服务器集成了 Gmail 和 Calendar API，允许 LLM 通过标准化的 MCP 协议访问和操作用户的 Gmail 邮箱和 Google 日历。

主要功能点

Gmail 集成:
- 获取 Gmail 用户信息
- 灵活查询邮件 (例如，未读邮件、来自特定发件人、日期范围、带附件的邮件)
- 获取完整邮件内容
- 创建新的草稿邮件
- 删除草稿邮件
- 回复邮件 (可立即发送或保存为草稿)
- 批量获取邮件
- 保存邮件附件到本地
Calendar 集成:
- 管理多个日历
- 获取指定时间范围内的日历事件
- 创建日历事件 (支持标题、时间、地点、描述、参与者、时区、通知等)
- 删除日历事件

安装步骤

OAuth 2.0 配置:

前往 Google Cloud Console 创建或选择项目。
启用 Gmail API 和 Google Calendar API。
创建 OAuth 客户端 ID，选择 "桌面应用" 或 "Web 应用程序"，配置 OAuth 同意屏幕，添加授权重定向 URI (例如 'http://localhost:4100/code')。

确保 OAuth 2.0 客户端配置包含以下 scopes:

[
  "openid",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/calendar",
  "https://www.googleapis.com/auth/userinfo.email"
]

- 下载客户端密钥 JSON 文件 (client_secrets.json) 并重命名为 '.gauth.json' 放置在项目工作目录。
- 创建 '.accounts.json' 文件配置 Google 账户信息，示例如下:
  ```json
  {
      "accounts": [
          {
              "email": "[email protected]",
              "account_type": "personal",
              "extra_info": "个人账号，包含家庭日历"
          }
      ]
  }

可以配置多个账户，'extra_info' 字段可用于向 LLM 提供关于账户的额外信息。

Claude Desktop 配置 (或其他 MCP 客户端):
- 找到 Claude Desktop 的配置文件 'claude_desktop_config.json' (MacOS: '~/Library/Application\ Support/Claude/claude_desktop_config.json', Windows: '%APPDATA%/Claude/claude_desktop_config.json')。
- 在 'mcpServers' 中添加 'fastmcp-gsuite' 服务器配置，配置启动命令和参数。

服务器配置

以下是 MCP 客户端 (如 Claude Desktop) 'claude_desktop_config.json' 配置文件中 'mcpServers' 字段下添加 'fastmcp-gsuite' 服务器的配置信息。请注意，MCP 客户端需要这些配置信息才能正确启动和连接到 MCP 服务器。

{
  "mcpServers": {
    "fastmcp-gsuite": {  // 服务器名称，客户端用此名称引用
      "command": "uv",  // 启动服务器的命令，这里假设使用 uv (uvicorn 的别名) 运行
      "args": [          // 传递给启动命令的参数
        "--directory",  // 指定工作目录
        "<fastmcp-gsuite 仓库路径>", //  **请替换为 fastmcp-gsuite 仓库的实际绝对路径**
        "run",          //  uv 命令的子命令，表示运行 Python 模块
        "fastmcp-gsuite" //  指定要运行的 Python 模块，对应仓库的入口点
      ]
    }
  }
}

参数注释:

'"fastmcp-gsuite"': 服务器的唯一名称，在 Claude 等 MCP 客户端中用于引用此服务器。
'"command": "uv"': 指定用于启动 MCP 服务器的命令。这里 'uv' 假设您的环境中已安装 'uv' (或者 'uvicorn') 并且在 PATH 环境变量中。您可能需要根据您的实际 Python 环境和包管理器调整此命令，例如使用 'python -m uvicorn' 或 'uvicorn'。
'"args": [...]': 一个字符串数组，包含了传递给 'uv' 命令的参数。
- '"--directory", "<fastmcp-gsuite 仓库路径>"': 指定 MCP 服务器的工作目录为 'fastmcp-gsuite' 仓库的根目录。务必将 '<fastmcp-gsuite 仓库路径>' 替换为您 fastmcp-gsuite 仓库在您本地文件系统中的绝对路径。 例如 '/Users/yourusername/Documents/fastmcp-gsuite'。
- '"run"': 'uv' 命令的子命令，用于运行一个 Python 模块或应用。
- '"fastmcp-gsuite"': 指定要作为 MCP 服务器运行的 Python 模块。这通常对应于仓库中定义了 'if name == "main": mcp.run()' 的主入口文件，例如 'src/mcp_gsuite/fast_server.py'，但在 'pyproject.toml' 中配置了入口点后，可以直接使用模块名 'fastmcp-gsuite'。

配置说明:

工作目录 ('--directory'): 指定正确的工作目录至关重要，确保服务器能够找到 '.gauth.json', '.accounts.json' 等配置文件以及项目依赖。
启动命令 ('command' 和 'args'): 请根据您的 Python 环境和包管理器进行调整。如果您使用 'venv' 或 'conda' 等虚拟环境，请确保 'uv' 命令在激活的虚拟环境中可用，或者使用虚拟环境中的 Python 解释器直接运行 'uvicorn'。
环境变量配置 (可选但推荐): 除了 'claude_desktop_config.json'，还可以通过环境变量或 '.env' 文件配置服务器，例如 'GAUTH_FILE', 'ACCOUNTS_FILE', 'CREDENTIALS_DIR' 等，具体参考仓库 README 中的 "Configuration Options" 部分。

基本使用方法

确保已完成 OAuth 2.0 配置和 Claude Desktop (或其他 MCP 客户端) 的服务器配置。
启动 FastMCP G Suite Server。根据您的配置，可能需要运行类似 'uv run fastmcp-gsuite' 命令 (在仓库根目录下)。
启动 MCP 客户端 (如 Claude Desktop)。客户端应能自动连接到 FastMCP G Suite Server。
在 MCP 客户端中，可以使用自然语言提示词调用服务器提供的工具，例如:
- "Retrieve my latest unread messages" (查询未读邮件)
- "What do I have on my agenda tomorrow?" (查询明日日程)
- "Create a calendar event with Tim for 2hrs next week." (创建日历事件)

具体提示词和工具使用方法请参考仓库 README 中的 "Example prompts" 和工具列表。

关键词