Gmail MCP Project

Gmail MCP服务器（FastAPI+Claude桌面版）

该项目提供了一个使用FastAPI构建的轻量级Gmail MCP服务器。它公开了一个REST端点（/api/v1/send email）以及一个MCP工具，可以由MCP兼容的客户端（如Claude Desktop）访问。这使您只需与AI助手交互即可发送真实的Gmail电子邮件。

它是如何工作的：

FastAPI应用程序提供了POST/neneneba api/v1/send-email端点，该端点使用Gmail api发送电子邮件。

MCP集成封装了这个FastAPI应用程序，并在/MCP处公开了一个MCP端点。

Claude Desktop连接到MCP服务器，并在您请求发送电子邮件时触发电子邮件发送工具。

______________________________________________________________________

1.项目结构

该项目遵循一个干净的架构，关注点分离：

MCP/
├── main.py                 # Application entry point
├── controllers/            # HTTP request handlers
│   ├── __init__.py
│   └── email_controller.py
├── services/              # Business logic layer
│   ├── __init__.py
│   ├── email_service.py   # Email business logic
│   └── gmail_service.py  # Gmail API operations
├── models/                # Data models (Pydantic)
│   ├── __init__.py
│   └── email_models.py
├── mcp_integration/       # MCP protocol integration
│   ├── __init__.py
│   └── tools.py
├── test_gmail_auth.py     # OAuth setup script
└── requirements.txt       # Python dependencies

关键文件：

• main.py –具有FastAPI应用程序工厂和MCP集成的应用程序入口点。
• controllers/email_controller.py –用于电子邮件操作的HTTP端点处理程序。
• services/email_service.py –电子邮件操作的业务逻辑。
• services/gmail_service.py –Gmail API服务（OAuth、MIME邮件创建、发送）。
• models/email_models.py –用于请求/响应验证的Pydantic模型。
• mcp_integration/tools.py –Claude Desktop集成的MCP工具定义。
• test_gmail_auth.py –执行Gmail OAuth和创建的一次性脚本 token.json.
• requirements.txt Python依赖关系。

不在Git中（必须由每个用户提供）：

• credentials.json –从Google Cloud下载的Google OAuth客户端机密。
• token.json –运行后在本地生成的Gmail访问/刷新令牌 test_gmail_auth.py.

______________________________________________________________________

2.先决条件

开始之前，请安装：

• Python 3.11+
• Node.js （为 npx –由Claude Desktop用于运行MCP网桥）
• 克劳德桌面版 （最新版本来自Anthropic网站）
• 可以访问Gmail的Google帐户

克隆仓库：

git clone 
cd MCP

______________________________________________________________________

3.设置Python环境

创建并激活虚拟环境：

python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows PowerShell
# or
source venv/bin/activate  # macOS/Linux

安装依赖项：

pip install -r requirements.txt

这安装FastAPI，Uvicorn，Gmail API库， mcp等等。

______________________________________________________________________

4.启用Gmail API并获取凭据

1. 转到 谷歌云控制台 并创建一个项目（或使用现有的项目）。
2. 在 API和服务→ 图书馆，启用 Gmail API 为了你的项目。
3. 在 API和服务→ 凭证，创建凭据：

- 类型： OAuth客户端ID - 应用程序类型： 桌面应用

1. 下载 credentials.json 将其归档并放置在 根 此项目的（与相同的文件夹 main.py).
2. 确保 credentials.json 是 不 致力于Git；它在里面 .gitignore.

______________________________________________________________________

5.运行一次Gmail OAuth(test_gmail_auth.py)

在venv激活的情况下 credentials.json 到位：

python test_gmail_auth.py

这有什么作用：

• 如果 token.json 如果不存在，它会打开一个浏览器窗口，用于谷歌登录和同意。
• 批准访问后，它将保存 token.json 在项目根中。
• 后续运行会重用或刷新此令牌，而不会要求您再次登录。

两者 credentials.json 和 token.json 是您的机器本地的，永远不应该提交。

______________________________________________________________________

6.启动Gmail MCP服务器

启动FastAPI+MCP服务器：

python main.py

或者直接使用uvicorn：

uvicorn main:app --reload

哪里 app 是在中创建的FastAPI实例 main.py.

默认情况下，这将在 http://127.0.0.1:8000.

6.1测试HTTP API（可选但推荐）

打开Swagger用户界面：

• 首选 http://localhost:8000/docs 在您的浏览器中。
• 找到 POST /api/v1/send-email.
• 点击 试试看 并使用JSON正文，如下所示：

{
  "to_email": "your-recipient@example.com",
  "subject": "MCP Gmail test",
  "body": "Hello from the Gmail MCP FastAPI server!"
}

点击 执行。您应该看到成功响应，并在目标地址收到电子邮件。

你也可以从 curl:

curl -X POST "http://127.0.0.1:8000/api/v1/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "your-recipient@example.com",
    "subject": "MCP Gmail test via curl",
    "body": "Hello from the Gmail MCP FastAPI server (curl)."
  }'

______________________________________________________________________

7.MCP终点

MCP服务器在以下位置公开：

http://localhost:8000/mcp

如果你在浏览器中打开该URL，你会看到一个JSON-RPC错误，如下所示：

{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Not Acceptable: Client must accept text/event-stream"}}

这是意料之中的。MCP over HTTP使用 服务器发送的事件，因此它需要特殊的标头。MCP客户端（如Claude Desktop）为您处理此问题。

______________________________________________________________________

8.连接到克劳德桌面

Claude Desktop需要一个 本地MCP过程 它通过stdio与MCP通信。我们使用一座名为 mcp-remote （通过运行 npx)它在Claude Desktop和您的HTTP MCP服务器之间转发。

8.1安装Node.js

如果你没有Node.js，请从官方网站安装最新的LTS。这给了你 npm 和 npx.

8.2编辑 claude_desktop_config.json

Claude Desktop将其配置存储在 claude_desktop_config.json。在Windows上，它通常位于：

C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json

在克劳德桌面中：

1. 打开 设置→ 开发者→ 编辑配置 打开此文件。
2. 在下面添加以下块 "mcpServers" （必要时与现有内容合并）：

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

• gmail-mcp 是Claude看到的此MCP服务器的名称。
• command 和 args 启动一个本地网桥进程，将Claude Desktop连接到您的HTTP MCP端点。

保存文件。

8.3重新启动克劳德桌面

1. 完全退出Claude Desktop（包括托盘图标）。
2. 再次启动Claude Desktop，以便重新加载配置。
3. 确保您的FastAPI服务器仍在运行(python main.py 或 uvicorn main:app --reload).

在新的聊天中，Claude现在应该能够使用 gmail-mcp 服务器。

______________________________________________________________________

9.使用Claude的Gmail MCP工具

一切都在运行：

1. 打开新的Claude Desktop聊天。
2. 问这样的问题：

“使用gmailmcp服务器向发送电子邮件 your-recipient@example.com 与主题 Test from Claude MCP 和身体 Hello from my local Gmail MCP server."

克劳德将：

• 发现 gmail-mcp 工具。
• 调用映射到的工具 POST /api/v1/send-email 随着 to_email, subject，以及 body.
• 您的FastAPI日志应显示正在发送的电子邮件。
• 您应该在收件人地址收到电子邮件。

______________________________________________________________________

10.安全说明

• 不要承诺 credentials.json 或 token.json Git。
• 仅在您自己的计算机上或安全的环境中运行此服务器；它有能力从您的Gmail帐户发送电子邮件。
• 对于演示，如果可能的话，请使用专用的Gmail帐户。

______________________________________________________________________

api参考

发布 /api/v1/send-email

通过Gmail API发送电子邮件。

请求正文：

{
  "to_email": "recipient@example.com",
  "subject": "Email Subject",
  "body": "Email body content",
  "is_html": false
}

答复：

{
  "success": true,
  "message": "Email sent successfully to recipient@example.com",
  "subject": "Email Subject"
}

MCP工具

send_邮件

使用Gmail API发送电子邮件。

参数：

• to_email （必填）：收件人电子邮件地址
• subject （必填）：电子邮件主题行
• body （必填）：电子邮件正文内容
• is_html （可选）：正文是否为HTML格式（默认值：false）

其他端点

获取 /api/v1/auth/status

检查Gmail身份验证状态并获取诊断信息。

答复：

{
  "authenticated": true,
  "credentials_file_exists": true,
  "token_file_exists": true,
  "message": "Authentication successful",
  "instructions": []
}

故障排除

1. 身份验证错误：

- 确保 credentials.json 位于项目根目录中 - 跑 test_gmail_auth.py 生成 token.json - 检查Gmail API是否已在谷歌云控制台中启用 - 访问 http://localhost:8000/api/v1/auth/status 检查身份验证状态

1. 连接错误：

- 验证FastAPI服务器是否在端口8000上运行 - 检查一下 mcp-remote 可以通过以下方式找到 npx - 确保已安装Node.js

1. MCP服务器未加载：

- 验证Claude Desktop配置中的路径 - 检查是否安装了所有依赖项 - 配置更改后重新启动Claude Desktop - 检查Claude Desktop日志是否有错误