Mcp Server

MCP Gmail 服务

此存储库提供 Gmail 的 MCP（Model Context Protocol）服务，让你能够通过 MCP 协议使用定义的工具（list_unread、search_emails）与 Gmail 帐户交互。它负责处理 Google OAuth2 身份验证，并提供基于 asyncio 的服务，以便与 Open WebUI 或其他 MCP 客户端集成。

功能

• list_unread：获取未读 Gmail 邮件的摘要。
• search_emails：根据 Gmail 查询条件搜索邮件（例如，from:[email protected]）。
• 无缝 OAuth2 流程，并缓存令牌。
• 基于 asyncio 的服务，可与 MCP 客户端（例如 Open WebUI）配合使用。

---

什么是 MCP？

Model Context Protocol（MCP）是一种开放标准，用于定义应用程序如何向大语言模型（LLM）提供上下文。可以将 MCP 视为一种标准化接口——类似于硬件领域的 USB-C——让 AI 模型能够与各种工具和数据源无缝连接。

---

为什么使用 mcpo？

虽然 MCP 服务功能强大，但它们通常通过标准输入/输出（stdio）进行通信，这可能会带来一些限制：

• 在不同环境中不安全。
• 与许多现代工具、UI 或平台不兼容。
• 缺少身份验证、文档和错误处理等功能。

mcpo（MCP-to-OpenAPI 代理）通过以下方式解决这些问题：

• 使用安全、可扩展的 HTTP 端点封装 MCP 工具。
• 让这些工具立即兼容现有的 OpenAPI 工具、SDK 和客户端。
• 为每个工具自动生成交互式 OpenAPI 文档。
• 使用纯 HTTP，无需设置套接字或编写特定于平台的代码。

这意味着你无需修改现有 MCP 服务代码，就能将 AI 工具部署到云端，与 Open WebUI 等 Web 界面集成，并提升安全性和可扩展性。

---

通过 mcpo 暴露 MCP Gmail 服务

要使用 mcpo 通过 OpenAPI 暴露 MCP Gmail 服务，请按照以下步骤操作：

1. 安装 mcpo：

   使用 pip：

   pip install mcpo
   

   或使用 uv（推荐，可更快启动）：

   uv pip install mcpo
   

2. 使用 mcpo 运行 MCP Gmail 服务：

   mcpo --port 8000 -- uv run gmail-server
   

   此命令会在端口 8000 上启动 mcpo 代理，并在其后运行 Gmail MCP 服务。

3. 访问 OpenAPI 文档：

   启动后，在浏览器中访问 http://localhost:8000/docs，查看为 Gmail 工具自动生成的 OpenAPI 文档。

4. 与 Open WebUI 集成：

   在 Open WebUI 中，通过指定端点（例如，http://localhost:8000）添加新的 OpenAPI 工具服务。这样，你就可以在 Open WebUI 界面中使用定义的工具与 Gmail 帐户交互。

---

将 mcpo 与 MCP Gmail 服务集成，可以提升其易用性、安全性，以及与现代工具和平台的兼容性，让你能够通过标准化 API 与 Gmail 帐户无缝交互。

---

前置条件

• Python 3.13 或更高版本
• uv 包管理器
• Google 帐户
• 在 Google Cloud Console 中创建项目和 OAuth 凭据的权限

项目结构

├── mcp_server/
│   ├── __init__.py       # Package initialization
│   └── gmail/
│       ├── __init__.py   # Module initialization
│       └── server.py     # Main server implementation
├── tests/
│   ├── __init__.py
│   └── test_gmail_server.py  # Test suite for Gmail server
├── secrets/
│   ├── credentials.json  # OAuth2 client credentials (downloaded)
│   └── token.json        # Cached user tokens (auto-created)
├── pyproject.toml        # Project metadata and dependencies
├── pytest.ini           # Pytest configuration
├── run_tests.sh         # Script to run tests with uv
├── Dockerfile           # Docker configuration
└── README.md            # This documentation

Gmail API 凭据设置

1. 前往 Google Cloud Console。
2. 创建新项目（或选择现有项目）。
3. 在 APIs & Services > Library 下启用 Gmail API。
4. 在 APIs & Services > OAuth consent screen 下，配置 External 同意屏幕：
   • 应用名称：MCP Gmail Server
   • 将你的电子邮件地址添加为 Test user（服务不会发布）。
5. 在 APIs & Services > Credentials 下，点击 Create Credentials > OAuth client ID。
   • 应用类型：Desktop app
   • 下载 JSON 文件。
6. 将下载的文件重命名为 credentials.json，并放入 secrets/ 目录。

安装

1. 克隆此仓库：

2. 如果尚未安装 uv，请先安装：

   pipx install uv
   

3. 使用 uv 创建并激活虚拟环境：

   # Create a virtual environment
   uv venv
   
   # Activate the virtual environment
   # On Unix/macOS:
   source .venv/bin/activate
   
   # On Windows:
   .\.venv\Scripts\activate
   

4. 使用 uv 安装依赖：

   # Install the package in development mode
   uv pip install -e .
   

配置

• 确保存在 secrets/credentials.json 文件。
• 首次运行时，系统会提示你在浏览器中授权应用；之后会创建 secrets/token.json 文件。

运行服务

通过以下命令启动 MCP 服务：

# Run directly with uv
uv run gmail-server

# Alternative: Run with MCP OpenAPI Proxy
uvx mcpo --port 8000 --api-key "your-api-key" -- uv run gmail-server

你应该会看到提示服务正在运行并等待 MCP 客户端连接的输出。

使用方法

• 连接任意兼容 MCP 的客户端（例如 Open Web UI）。
• 使用以下工具/操作：
  • list_unread：返回未读邮件摘要。
  • search_emails：返回与提供的 Gmail 查询条件匹配的邮件。

Docker 设置

项目包含一个用于容器化的 Dockerfile：

1. 构建 Docker 镜像：

   docker build -t gmail-mcp-server .
   

2. 运行 Docker 容器：

   docker run -p 8000:8000 \
     -e API_KEY="your-secure-api-key" \
     gmail-mcp-server
   

Docker 配置详情

• 基础镜像：Python 3.13-slim
• 依赖项：使用 uv 安装
• 卷挂载：/app/secrets 应包含你的 Google OAuth 凭据
• 环境变量：
  • API_KEY：MCP OpenAPI 代理的安全密钥（默认值："top-secret"）
• 端口：开放 8000 端口，用于 MCP OpenAPI 代理

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。